# 🧹 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 "/console.mjs" open --workflow finalize` before reading (: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; `--spec specs/` 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 `` 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 "/specs.mjs" list` / `status `: specs on disk; one spec's phases, task counts by marker, completion and `checks`. `status` also reads an archived spec. - `node "/specs.mjs" archive [--dry-run]`: the Step 6 move, verified. - `node "/specs.mjs" metrics --step finalize --set ...`: Step 7's METRICS_JSON line. - `node "/feedback-payload.mjs"`: Step 6.5 (see its reference). - `node "/commit-msg.mjs" --subject ""`: the commit command. - `node "/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//` (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//` 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 `. 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 | 2. 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`): ```markdown ## Task Completion Audit | Phase | Total | Completed | Blocked | Incomplete | |-------|-------|-----------|---------|------------| | Phase 1 | X | X | 0 | 0 | | **Total** | **X** | **X** | **X** | **X** | ``` 3. 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`): ```markdown 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. ```markdown ## 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: ```markdown ## 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. ```markdown ## 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): ```markdown ## 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 --dry-run` and show the user its `files`; ask "Archive it? (yes / no / show me)"; on their yes, `specs.mjs archive `. It moves the whole folder to `specs--completed//` (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 "/console.mjs" forget --spec specs/` (: 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. ```markdown ## Finalization Complete ### Summary - **Feature:** [Name] - **Status:** Complete - **Completion Rate:** [X]% ([Y]/[Z] tasks) - **Archived To:** `specs--completed//` Paste the `comment` from `specs.mjs metrics once archived, else specs/> --step finalize --set verification_failures_found= --set documentation_updates_needed=`: 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//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//] ``` --- ``` ⋅ ╭───╮ ╲│ ★ │╱ │ ◡ │ You did it! Feature complete! ╰┬─┬╯ ``` > IMPLEMENTATION COMPLETED! > All tasks finished. > Specs archived to `specs--completed//`. > 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 "`. 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//`. **On the web console:** the completion summary is printed to a terminal the browser user is not watching.