Review, Commit, Advance

Tests pass and the smoke test looks good. Before committing, run a self-review against the spec — not a generic code review, but a targeted check that the implementation matches the contract from Phase 2. This catches issues that tests don't cover: wrong error format, inconsistent patterns, spec deviations.

Self-review at implementation time costs roughly 5-10% of session tokens. The same review done as a separate PR review costs 50-100% (new session, re-read all code, re-learn context). Review early, review cheap.

Claude catches the 60-70% of issues that are mechanical (wrong format, missing handler, inconsistent pattern). You focus on the 30-40% that require judgment (business logic, naming, architecture). Together, the review is faster and more thorough than either alone.

Here is the prompt that performs a targeted self-review:

Review the implementation you just built.

Check against:
- Feature spec: docs/specs/task-comments.md
- Architecture: docs/architecture/task-comments.md
- CLAUDE.md conventions

For each issue:
1. Severity: critical / warning / suggestion
2. File and line
3. What's wrong
4. Proposed fix

Do NOT report style issues.

You could paste this into Claude right now and get a review. But you'll run this same check after every feature — and Phase 4's Ralph Loop will run it on every deferred unit automatically. Rather than copy-paste it each time, package it as a skill once and invoke it with a slash command from then on.

Same pattern as validate-spec and design-review: a markdown file in .claude/skills/ that becomes a slash command. Type /self-review task-comments and the review runs against that feature's artifacts.

You are in the taskflow folder with the implementation complete and tests passing. Create the skill directly from the shell, start a fresh session, and run the review with it.

Step 1 — Exit Claude: A skill is just a file on disk. Drop to the shell and create it directly.

Run in terminal:

1
/exit

Step 2 — Write the skill file: Create .claude/skills/self-review/SKILL.md with the frontmatter and body below. The $ARGUMENTS placeholder is replaced at runtime with whatever you pass after /self-review.

Run in terminal:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
mkdir -p .claude/skills/self-review && cat > .claude/skills/self-review/SKILL.md << 'EOF'
---
name: self-review
description: Review implementation against spec, architecture, and conventions. Use after completing a feature before committing.
disable-model-invocation: true
argument-hint: [feature name or description]
---

Review the $ARGUMENTS implementation.

Check against:
- Feature spec in docs/specs/
- Architecture docs in docs/architecture/
- CLAUDE.md conventions

For each issue found:
1. Severity: critical / warning / suggestion
2. File and line
3. What's wrong
4. Proposed fix

Do NOT report style-only issues that a linter would catch.
EOF

Observe: The skill file now exists on disk. Nothing about this required an LLM — that is the point. Skills are plain text contracts that Claude reads when you invoke them.

Step 3 — Start a new session: Skills are discovered at session start, so the next claude invocation will pick it up.

Run in terminal:

1
claude

Step 4 — Run the review: Invoke the skill against the implementation you just built. This is the self-review gate — you just run it through the skill instead of pasting the prompt.

Tell Claude:

/self-review task-comments

Observe: Claude typically finds 2-4 issues: a missing error case, an inconsistency with the error format defined in the architecture, a validation rule that doesn't quite match the spec. Note the severity ratings — critical issues should be fixed now, suggestions can wait.

Step 5: Fix review findings

Ask Claude to fix all critical and warning issues:

Tell Claude:

Fix all critical and warning issues from your review.
Run the tests to make sure fixes don't break anything.

Observe: Claude makes targeted fixes. The fixes should address specific spec deviations, not general 'improvements.' Tests still pass after the fixes.

Step 6: Update backlog

Update the backlog to mark the ACTIVE unit as complete:

Tell Claude:

In requirements/backlog.md, mark the ACTIVE unit as COMPLETE.
Note which acceptance criteria passed and the test file location.

Leave all DEFERRED units unchanged — each one follows the same
test-first pattern when its turn comes.

Observe: The backlog now shows the ACTIVE unit as complete with a clear trail. Deferred units remain untouched — when picked up, each follows the same test-first pattern: generate tests from acceptance criteria, then implement to pass them.

Verify what Phase 3 produced:

These artifacts feed the optional Ralph Loop directly. External lint, test, and browser gates keep the automated pipeline supervised before it advances.