/sparc-refine

name: sparc-refine
description: Run the SPARC Refinement and Completion phases — review code, improve test coverage, validate against specification, and generate documentation
argument-hint: ""
allowed-tools: mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_search mcp__plugin_ruflo-core_ruflo__memory_retrieve mcp__plugin_ruflo-core_ruflo__task_create mcp__plugin_ruflo-core_ruflo__task_update mcp__plugin_ruflo-core_ruflo__task_complete mcp__plugin_ruflo-core_ruflo__hooks_intelligence_trajectory-step mcp__plugin_ruflo-core_ruflo__hooks_intelligence_trajectory-end mcp__plugin_ruflo-core_ruflo__neural_train mcp__plugin_ruflo-core_ruflo__neural_predict Bash Read Write Edit

SPARC Refinement + Completion

Run Phases 4 and 5 of the SPARC methodology: iteratively improve through code review and testing, then finalize with validation, documentation, and deployment readiness.

When to use

After the Architecture phase is complete and its gate has been passed. This skill covers the final two phases that bring a feature from implemented to production-ready.

Steps

Phase 4 — Refinement

1. **Retrieve all prior artifacts** — call `mcp__plugin_ruflo-core_ruflo__memory_search` with namespace `sparc-phases` and query for the feature slug. Load spec (acceptance criteria), pseudocode, and architecture.

2. **Retrieve phase state** — call `mcp__plugin_ruflo-core_ruflo__memory_retrieve` with namespace `sparc-state` and exact key `current-phase-{feature-slug}` to confirm we are in Phase 4 (or Phase 5 when resuming completion). If `status === "complete"`, report the existing completion and do not write again; stop on missing/malformed state.

3. **Code review** — review the implementation against: a. **Specification compliance**: does every acceptance criterion have a corresponding code path? b. **Architecture adherence**: do modules follow the defined boundaries and dependency rules? c. **Pseudocode fidelity**: does the implementation match the designed algorithms? d. **Code quality**: naming conventions, single responsibility, error handling, no dead code e. Document findings as review comments

4. **Test coverage analysis**: a. Run existing tests and measure coverage b. Identify uncovered acceptance criteria c. Write missing tests:

• Unit tests for each public function
• Integration tests for cross-module interactions
• Edge case tests for each identified edge case from the spec

d. Target coverage >= 80% on new code

5. **Performance validation** — if the spec includes performance constraints: a. Profile critical paths identified in the pseudocode b. Compare measured performance against constraint thresholds c. Optimize if thresholds are not met

6. **Iterate** — repeat steps 3-5 until:

• All acceptance criteria have passing tests
• Code review has no critical or high-severity issues
• Coverage meets the threshold
• Performance constraints are satisfied

7. **Store refinement artifact** — call `mcp__plugin_ruflo-core_ruflo__memory_store` with namespace `sparc-phases`, key `refine-{feature-slug}`, value: `{ status: "complete", reviewFindings: [...], coveragePercent: N, performanceResults: {...}, iterations: N }`

Before moving to Phase 5, evaluate the Phase 4 gate (passing acceptance tests, approved review, coverage >= 80%) and store its evidence in `sparc-gates`. On failure preserve phase, increment gateAttempts, refresh `updatedAt` with the current ISO timestamp at the exact current-phase key, report blockers and stop. On pass preserve existing state fields, set phase 5, phaseName "Completion", status "active", and `updatedAt` to the current ISO timestamp at the same key in `sparc-state`. When resuming Phase 5, do not repeat the Phase 4 transition.

8. **Record trajectory step** — call `mcp__plugin_ruflo-core_ruflo__hooks_intelligence_trajectory-step` with refinement summary

Phase 5 — Completion

9. **Full regression** — run the complete test suite to verify no regressions from refinement changes

10. **Traceability matrix** — build a matrix mapping every acceptance criterion to:

• The test(s) that verify it
• The code file(s) that implement it
• The current pass/fail status

11. **Documentation**: a. Generate API documentation from code comments and type definitions b. Write usage examples for key public interfaces c. Update any existing documentation affected by the changes

12. **Deployment readiness checklist**:

• [ ] All tests passing
• [ ] Documentation complete
• [ ] Database migrations prepared (if applicable)
• [ ] Configuration changes documented
• [ ] Feature flags configured (if applicable)
• [ ] Rollback plan defined
• [ ] Security review complete (no secrets, inputs validated)

13. **Evaluate the final Phase 5 gate** — completion is allowed only when final gate evidence for every criterion passes: full regression actually ran and passed, documentation is complete, deployment checklist is verified, and traceability links every acceptance criterion to passing tests. Store the actual pass/fail evidence at `gate-5-{feature-slug}-{timestamp}` in `sparc-gates`. If evidence is missing, failed, interrupted, or unrun, preserve state and phase, increment gateAttempts, refresh `updatedAt` to the current ISO timestamp at the exact current-phase key, report blockers and stop. Do not store a complete artifact or complete the state, set completedAt, or train a successful cycle on failure.

**After the final gate passes, store completion artifact** — call `mcp__plugin_ruflo-core_ruflo__memory_store` with namespace `sparc-phases`, key `complete-{feature-slug}`, value: `{ status: "complete", traceabilityMatrix: [...], documentationFiles: [...], deploymentChecklist: {...}, regressionResult: "pass" }`

**Close the workflow** — retrieve `current-phase-{feature-slug}` exactly from `sparc-state` again and decode it as `state`. If `s