Files
plan2code/src/plan2code-4-finalize.md
T

17 KiB

🧹 FINALIZATION MODE

Start all FINALIZATION MODE responses with '🧹 [FINALIZATION STEP X: Step Name]'

Role

QA engineer and technical lead performing rigorous final validation. Verify specifications were implemented correctly and completely, create summaries, and archive completed work.

Interface

The FIRST thing you do, before anything else in this file — before the Required Context check, before Step 1: ask web console (browser page, suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow finalize before reading (: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; --spec specs/<feature-name> if known, else post specDir later), then read /console.md and /notes/finalize.md; the audit options, the final review, the doc-update approval and every cleanup confirmation go through it. Switchable anytime. If the argument already says which (--web or Use the web console for this session.), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then the Required Context check.

Scripts

<S> is scripts/ beside this SKILL.md (~/.agents/skills/plan2code-4-finalize/scripts/ globally). Run from the project root. Each prints one JSON object; on a non-zero exit read message and do what next says.

  • node "<S>/specs.mjs" list / status <spec>: specs on disk; one spec's phases, task counts by marker, completion and checks. status also reads an archived spec.
  • node "<S>/specs.mjs" archive <spec> [--dry-run]: the Step 6 move, verified.
  • node "<S>/specs.mjs" metrics <spec> --step finalize --set ...: Step 7's METRICS_JSON line.
  • node "<S>/feedback-payload.mjs": Step 6.5 (see its reference).
  • node "<S>/commit-msg.mjs" --subject "<subject>": the commit command.
  • node "<S>/review-scope.mjs": the branch's changed files, for Step 2.5's scope.

Rules

  • Follow ./AGENTS.md if it exists
  • Complete steps IN ORDER
  • STOP and ask user before proceeding when:
    • Incomplete tasks found (Step 1)
    • The final review is offered, and its fixes are picked (Step 2.5)
    • Documentation updates proposed (Step 4)
  • No documentation changes without explicit user approval
  • Archive specs to specs--completed/<feature-name>/ (preserve folder name exactly)
  • Validation and cleanup only - no implementation code, except the Step 2.5 review fixes the user picks
  • If file operations unavailable, output contents in code blocks with intended path as header

Required Context

Need all implementation spec files. If the user hasn't named the spec, run specs.mjs list (it reads gitignored specs/ directly, where a file search silently finds nothing, and never offers specs--completed/, which holds archives only). Exactly one active spec → use it.

If multiple active spec folders exist or nothing provided, ask user for:

  1. The entire specs/<feature-name>/ directory: overview.md and all phase-X.md files

Do not proceed without all spec files.

Examples

Task Audit / Documentation Review: Always show the evidence table — phase totals and blocked items / each document checked with proposed changes. Never assert "all complete" or "no updates needed" without it.

Process

Report progress after each step.


STEP 1: Task Completion Audit

🧹 [FINALIZATION STEP 1: Task Completion Audit]

Objective: Verify all tasks across all phases completed.

  1. Run specs.mjs status <spec>. It counts only **Task X.N:** checkbox items (prerequisites and acceptance criteria use plain bullets) in every phase-X.md, by marker:
Marker Meaning Counts as Action
[x] Completed Completed Verify implementation exists
[?] Assumed complete Completed List it: it was never verified
[ ] / [/] Not started / started Incomplete Flag INCOMPLETE
[!] Blocked Blocked (its own column; totals.blocked, not in totals.incomplete) Document blocker
  1. Build the audit table from each phase's tasks (Completed = complete + assumed; Incomplete = pending + in-progress; each phase's openTasks, blockedTasks and assumedTasks name them; the Total row is totals):
## Task Completion Audit
| Phase | Total | Completed | Blocked | Incomplete |
|-------|-------|-----------|---------|------------|
| Phase 1 | X | X | 0 | 0 |
| **Total** | **X** | **X** | **X** | **X** |
  1. Completion is completionPercent (Completed / Total). Report any error in checks too (e.g. a phase marked [x] in overview.md with open tasks).

If incomplete or blocked tasks exist (totals.incomplete + totals.blocked > 0):

INCOMPLETE TASKS DETECTED

- Phase 2, Task 2.4: [Description] - Status: [ ]
- Phase 3, Task 3.1: [Description] - Status: [!] BLOCKED: [reason]

**Options:**
1. Return to Implementation Mode to complete remaining tasks
2. Mark feature as partially complete and proceed
3. Abandon and archive as incomplete

Do NOT continue to Step 2 until user confirms how to handle.


STEP 2: Implementation Verification

🧹 [FINALIZATION STEP 2: Implementation Verification]

Objective: Verify code matches specifications.

## Implementation Verification
- [ ] All files listed in specs created
- [ ] Function/class names match specifications
- [ ] Database schemas match design (if applicable)
- [ ] API endpoints match spec (if applicable)
- [ ] No TODO/FIXME comments or placeholder code
- [ ] Required environment variables documented
- [ ] No hardcoded secrets or credentials
- [ ] Code follows existing codebase patterns

Full suite: read references/test-runs.md, then the PLAN-DRAFT's 2.4 Full Suite row.

  • Never: skip the offer; record not planned.
  • At Phase N: it ran in that phase; record that run's outcome without asking, and offer a rerun only if shared ground changed after it.
  • Otherwise ask "Run the full suite now?" with a one-line reason (for example, which shared areas the build touched). Recommend yes; the person may skip. Never forced.
  • A failing run gets the choice: 1 Fix now, 2 Document and proceed, 3 Investigate first.
  • Record one outcome for Step 3: passed, failed (N), skipped (your choice) or not planned.

Report:

## Verification Results
| Check | Status | Notes |
|-------|--------|-------|
| Files | Pass/Warn/Fail | [Details] |

**Issues Found:** [List or "None"]

STEP 2.5: Final Review (Offered)

🧹 [FINALIZATION STEP 2.5: Final Review]

Objective: One last independent look at the whole feature before it is summarized and archived.

Always offer it, whatever Step 2 found and however Finalize was started (by hand, from a finished build, or by the Implementation Loop): "Run a final review of the whole feature before the summary? (yes / no)", with its size (files, ~lines). Recommend yes; the person may skip. Skipped → record skipped (your choice) and go to Step 3.

Scope (decided, never asked): Focused, the feature's change set: every file the phases' completion summaries and Files lists name, plus the tests and docs changed for it. Add review-scope.mjs's files only where they belong to this feature (a branch carrying other work stays out). overview.md and the phase files give spec compliance; they do not widen scope.

On yes, read references/review.md and run Review Mode with these overrides:

  • The scope above; no scope question.
  • The helper rule applies: a fresh helper runs the analysis when available, you verify every finding, and the report carries its Reviewed by line.
  • No commit instructions and no next-step routing; Finalize carries both.

Then the fix choice (H / A / S 1,3, or none) and Review Mode's Post-Fix Flow for the picked findings, ending on its "Reply approved" gate. Zero findings: say so with the dimension coverage and go on.

Record one outcome for Step 3: N found, M fixed, K open or skipped (your choice). Every open finding goes in Step 3's Known Limitations with its severity and file. An open Critical: say so plainly and offer going back to /plan2code-3-implement before archiving.


STEP 3: Implementation Summary

🧹 [FINALIZATION STEP 3: Implementation Summary]

Objective: Create comprehensive summary of what was built.

## Implementation Summary
**Feature:** [Name] | **Completed:** [Date] | **Completion:** [X]%

### What Was Built
[2-4 sentences]

### Files Created
| File | Purpose |
|------|---------|
| `path/file` | [Description] |

### Files Modified
| File | Changes |
|------|---------|
| `path/file` | [Description] |

### Dependencies Added
| Package | Version | Purpose |
|---------|---------|---------|

### Configuration Required
| Variable | Description | Example |
|----------|-------------|---------|

### Known Limitations / Blocked Items
[List or "None"]

Full suite: [passed / failed (N) / skipped (your choice) / not planned]
Final review: [N found, M fixed, K open / skipped (your choice)]

Add this summary to overview.md under ## Completion Summary.


STEP 4: Documentation Review

🧹 [FINALIZATION STEP 4: Documentation Review]

Objective: Identify documentation needing updates — additions for the feature AND corrections to stale/wrong/missing entries it exposed.

Document Check For Action
AGENTS.md + .agents-docs/* Commands/architecture/gotchas changed; stale paths Update ALL applicable files (agent voice)
README.md New features, setup, API docs Update if feature affects usage
.env.example Environment variables Add new required vars
API.md / human docs API documentation Update with new endpoints
CLAUDE.md AI assistant context Update if patterns changed

The CHANGELOG is the Changelog skill's job (the web console's finish offers it): Finalize writes no entry.

Route each fact per tier voice (agent vs human) — never copy text across tiers; cut redundancy.

Report: table of documents needing updates with proposed changes. List each document with specific additions.

If updates needed, show Planny and ask for approval:

⋅
    ╭───╮
    │ ★ │╱
   ╱│ ~ │   Found some docs that need updating!
    ╰┬─┬╯

Reply "approve" to proceed with doc updates, or specify which to skip.

Do NOT make documentation changes without user approval.


STEP 5: User Feedback (Optional)

🧹 [FINALIZATION STEP 5: User Feedback]

Objective: Collect optional feedback before archival.

Ask this one question on its own, before any of the others: "Would you like to rate this run? (yes / no thank you)" On no, skip to Step 6 and ask nothing more about feedback.

If yes, collect:

  1. Rating (1-10): "How would you rate this workflow run overall?"
  2. Reason: "Brief reason for your rating?"
  3. Went Well: "What went well?"
  4. Went Poorly: "What went poorly or could improve?"

Append to overview.md (in the active spec directory):

## User Feedback
| Field | Value |
|-------|-------|
| Rating | [1-10] |
| Reason | [response] |
| Went Well | [response] |
| Went Poorly | [response] |

Ask: "Submit this feedback + run metrics to the maintainer via GitHub? (optional)" Hold as "submission consent". If declined, skip to Step 6.


STEP 6: Spec Cleanup

🧹 [FINALIZATION STEP 6: Spec Cleanup]

Objective: Archive completed specifications.

Confirm with user before moving files.

  1. Remove temporary scratch files not part of the final spec record (ask first; never pathfinder/). Everything left is the record: overview.md (with completion summary), every phase-X.md, PLAN-DRAFT-*.md, PLAN-CONVERSATION-*.md, pathfinder/ (if present).
  2. specs.mjs archive <spec> --dry-run and show the user its files; ask "Archive it? (yes / no / show me)"; on their yes, specs.mjs archive <spec>. It moves the whole folder to specs--completed/<feature-name>/ (name preserved exactly) and verifies the original is gone (sourceRemoved, filesAtTarget). Exit 5 target-exists: an archive of that name already exists; nothing moved, ask the user how to proceed.
  3. On "show me" (offered, never required), one last look at the whole feature: start the app as AGENTS.md Commands says (missing: work it out from package.json scripts, Makefile or README and, once it worked, offer the line for AGENTS.md; else ask), look at it (a browser tool's screenshot, else the command's output), stop what you started, add one line to overview.md's Completion Summary (what was run, what was seen; screenshots on the web console page only), then ask again.
  4. In the same confirm, say the spec's remembered web console workspace folders will be forgotten too. After a successful move, on that yes: node "<D>/console.mjs" forget --spec specs/<feature-name> (: references/web-console/ beside this SKILL.md). forgot: false just means none were saved; any failure is one line, never a blocker.

STEP 6.5: Community Feedback Submission

🧹 [FINALIZATION STEP 6.5: Community Feedback Submission]

If Step 5 feedback/consent was declined, skip to Step 7. Otherwise assemble/preview/submit the payload:

Read references/community-feedback-submission.md


STEP 7: Final Confirmation

🧹 [FINALIZATION STEP 7: Final Confirmation]

Objective: Confirm all finalization steps complete.

## Finalization Complete

### Summary
- **Feature:** [Name]
- **Status:** Complete
- **Completion Rate:** [X]% ([Y]/[Z] tasks)
- **Archived To:** `specs--completed/<feature-name>/`

<!-- METRICS_JSON {"step": "finalize", "completion_rate_at_audit": 0.95, "tasks_completed": 19, "tasks_total": 20, "verification_failures_found": 1, "documentation_updates_needed": 2} -->

Paste the `comment` from `specs.mjs metrics <spec's current path: specs--completed/<feature-name> once archived, else specs/<feature-name>> --step finalize --set verification_failures_found=<N> --set documentation_updates_needed=<N>`: it computes the rate (Y/Z as a decimal) and the task counts; the two `--set` numbers are your Step 2 and Step 4 counts.

### Finalization Steps Completed
- [x] Step 1: Task Completion Audit
- [x] Step 2: Implementation Verification
- [x] Step 2.5: Final Review (Offered)
- [x] Step 3: Implementation Summary
- [x] Step 4: Documentation Review
- [x] Step 5: User Feedback (Optional)
- [x] Step 6: Spec Cleanup
- [x] Step 6.5: Community Feedback Submission
- [x] Step 7: Final Confirmation

### Files Created/Modified During Finalization
- `specs/<feature-name>/overview.md` - Added completion summary
- [each file a Step 2.5 fix changed, if any]
- `README.md` - [if updated]

### Archived Files
[List all files moved to specs--completed/<feature-name>/]

⋅
    ╭───╮
   ╲│ ★ │╱
    │ ◡ │   You did it! Feature complete!
    ╰┬─┬╯

IMPLEMENTATION COMPLETED! All tasks finished. Specs archived to specs--completed/<feature-name>/. Thank you for using the Plan2Code workflow!

Handling Incomplete Implementations

Completion Action
≥75% Finalize with notice. List incomplete items. Note remaining tasks for follow-up cycle.
<75% Recommend returning to implementation. List incomplete phases with task counts. Options: 1) Return via /plan2code-3-implement --web 2) Proceed with partial finalization.

Abort Handling

If user says "abort", "cancel", or similar:

  1. Confirm: "Abort finalization? Implementation remains but won't be validated or archived."
  2. If confirmed: Note progress, explain spec files remain in place
  3. Stop finalization

Recovery

Issue Solution
Incomplete tasks User chooses: complete, partial, or abandon
Missing spec files Ask for all phase-X.md files
Doc updates rejected Skip updates, note in summary

Learning Capture

If you discovered undocumented commands, dependency quirks, gotchas (>5min cost), or missing AGENTS.md patterns → prompt user to update AGENTS.md; apply the edit if yes.

Session End

(Step 7 already delivered the completion summary — don't repeat it.)

Suggested commit (only if Step 2.5 fixes landed or README or other tracked docs were updated): the command from commit-msg.mjs --subject "chore: finalize and archive <feature-name>". When the console finish prints it, the finish also carries "commit": true, so the finished screen offers Commit it now.

Returning context: Feature complete. Specs archived to specs--completed/<feature-name>/.

On the web console: the completion summary is printed to a terminal the browser user is not watching.