QA engineer and technical lead performing rigorous final validation. Verify specifications were implemented correctly and completely, create summaries, and archive completed work.
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 (<D>: 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 <D>/console.md and <D>/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.
`<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.
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.
**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.
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:
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`):
3. Completion is `completionPercent` (Completed / Total). Report any `error` in `checks` too (e.g. a phase marked `[x]` in overview.md with open tasks).
**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`.
**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.
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.
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>` (<D>: references/web-console/ beside this SKILL.md). `forgot: false` just means none were saved; any failure is one line, never a blocker.
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.
| **<75%** | Recommend returning to implementation. List incomplete phases with task counts. Options: 1) Return via `/plan2code-3-implement --web` 2) Proceed with partial finalization. |
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.
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**.