Execution: Implement & Review

Execution is the daily development loop. You pick up a refined story, implement it task by task, create a PR, and get it reviewed and merged.

Step 8: Implement

Develop a user story by working through its tasks sequentially.

The Implementation Cycle

For each task, the skill follows a strict 5-step cycle:

1. Context ──── Load adoption files and technical decisions
       │
2. Branch ───── Create or switch to the feature branch
       │
3. Implement ── Write code (TDD for dev tasks, direct for docs/config)
       │
4. Quality ──── Run quality gates (lint, test, type check)
       │
5. Commit ───── Commit and update task checkbox in the story

TDD Discipline (Development Tasks)

The AI follows strict TDD, tests and implementation never change in the same session:

1. RED: write a failing test that defines the expected behavior
2. GREEN: write the minimal code to make the test pass
3. REFACTOR: improve structure without changing behavior

Every new module file must have a corresponding unit test file (1:1 mapping). Mocks are avoided in favor of in-memory test doubles.

Commit Strategies

With commit-per-task, the developer gets a checkpoint between every task: the AI presents a summary and waits for confirmation before committing.

Progress Feedback: Ticks and One Comment

While the skill works through the breakdown, the story reports its own progress. As each task completes, its checklist item in the story's Task Breakdown is ticked (located by task ID, patched one line at a time, never rewriting another section) and the outcome is queued. At the end of the run, the queue is flushed as one comment: a headline, one line per task, everything longer collapsed in <details>.

The cadence is one comment per run iteration, so an unattended run reports at task granularity without turning the story into a comment feed. A task that failed or was skipped is recorded in the comment and its checklist item stays unticked: a story that stopped halfway looks different from one that finished.

The feedback is annotation, never a gate: a locator mismatch, a body edited concurrently, or a tracker write that does not land is retried once, then reported in the comment, and the run carries on.

That holds through the writer too: the tick is composed with $on-failure: report, so a tracker error comes back as an outcome to record rather than as a halt that would stop the story it only annotates.

Three rules make that safe, and the shipped guideline task-progress-feedback.md (installed into your project at .pair/knowledge/guidelines/collaboration/project-management-tool/, listed in the guidelines catalog) states them in full: the item is located by task ID, never by position or title; the write is diff-checked to exactly one changed line, one checkbox per write, or it is abandoned rather than sent; a conflicting body is re-read and re-located, never re-patched from the stale snapshot.

Closing Phase: Checkpoint + PR

After all tasks are complete, the skill's closing phase splits the handoff from the publish so the PR is always built on a clean context:

1. Writes a checkpoint (/pair-capability-checkpoint in write mode): the boundary artifact capturing story, branch, tasks done, decisions, and remaining todos. This is the handoff document the PR is built from, not this session's memory.
2. Publishes the PR via a handoff-only subagent: spawns a fresh, anonymous subagent whose entire prompt is the checkpoint, which resumes from it and runs /pair-capability-publish-pr. That skill runs the quality gate, pushes the branch, creates or updates one PR from the PR template, links it to the story, copies the classification tags, and marks it ready for review.

If subagent spawning is unavailable, the skill degrades to running /pair-capability-publish-pr inline in the same session (checkpoint still written) and notes the degradation. Re-invoking /pair-process-implement on an interrupted story reads the checkpoint and resumes from the first pending task, completed tasks are never repeated, and publish-pr updates the existing PR rather than opening a second one.

What Your PR's Tier Changes

The risk:* tag copied from your story onto the PR (see the closing phase above) is what scales the rest of the flow. Five things change with it; the model behind each is linked, not repeated here.

1. Review re-classifies from the diff: it may raise, never lower (D17). The tier from refinement is a floor. If the actual diff is riskier than the story implied, review raises it and says so; if it is safer, the tier stays. Raising only ever widens what runs.
2. Gates scale with the tier. The pre-merge gate reads the tag and runs the checks that tier needs: the matrix is in Tag-Driven Quality Gates. Locally, /pair-capability-verify-quality runs the same set before you push.
3. Review effort scales with the tier. Green: no human review wait, the AI review is informational. Yellow: blocked until one reviewer approves, within one working day. Red: blocked until an explicit approval, within two working days. These are KB defaults a project can override per tier; the full table is in the Quality Model.
4. The PR moves through three states: to-be-reviewed, ready-to-merge, not-approved: synthesized from gate, review and tier; you never set them by hand. See PR State Flow.
5. No tag means red. A PR with no resolvable risk:* tag is gated as 🔴 and runs the full matrix with a warning: missing classification never means fewer checks.

Step 9: Code Review

Review a pull request through a structured 6-phase process.

The Review Phases

Phase 1 ── Validation ────── PR structure, linked story, classification (risk floor)
       │
Phase 2 ── Technical ─────── Code quality, security, cost, architecture (coupling)
       │
Phase 3 ── Adoption ──────── Libraries match tech-stack.md, patterns match architecture.md
       │
Phase 4 ── Completeness ──── All AC covered, all tasks done, DoD met
       │
Phase 5 ── Decision ──────── APPROVED, CHANGES REQUESTED, or REJECT
       │
Phase 6 ── Merge ─────────── Merge PR, update story/epic/initiative status

The Verdict-First Review Body

The review is submitted as the native GitHub review (the verdict is the Approve / Request Changes / Comment action): there is no separate review comment. Its body is verdict-first so a reader understands the outcome in about 30 seconds (D22):

• Top: classification tags (risk:<tier> · cost:<class>), the decision, and a one-line reason. If the review-time classification differs from the story's refinement-time one, a Classification changed line states the change: it only ever fires upward (the review value is a floor: it may raise a tier, never lower it).
• Assessments (each a one-line verdict, details collapsed): security: input validation, output handling, authentication, authorization, introduced vulnerabilities (from /pair-capability-assess-security); cost class (from /pair-capability-assess-cost); architecture / coupling balance (from /pair-capability-assess-coupling); bug fix, red test before fix.
• When a capability is not installed, its section reads not assessed, explicit, never silently dropped.

The Bug-Fix Red Test

Test-first bug fixing is policy (AGENTS.md § Bug Resolution Workflow), and the review is where it is verified instead of assumed. On a bug-fix PR the reviewer names the test that reproduces the bug and how the diff shows it failing-before / passing-after; a bug fix with no reproducing test and no recorded rationale is a Major finding: the fix has not proven it addresses the bug.

The condition is half the check: a feature PR carries no test-first obligation, so its verdict reads not applicable, not a bug fix (written out, never dropped), and a genuinely untestable fix (a doc typo, a pure-formatting change) is closed by an explicit one-line rationale rather than a blocked merge. It is reviewer judgment aided by the checklist prompt, pair runs no automated commit-order analysis.

ADR Enforcement

If the review detects a new library not listed in tech-stack.md or an architecture pattern not recorded in architecture.md, it blocks and requests an Architecture Decision Record before approval. This ensures every technical choice is deliberate and documented.

Parent Cascade

After merge, the skill updates the status hierarchy:

• Story → Done
• If all stories in the epic are Done → Epic → Done
• If all epics in the initiative are Done → Initiative → Done

The Complete Loop

/pair-next → suggests story to implement
    │
/pair-process-implement #story-id
    │
    ├── Task 1: RED → GREEN → REFACTOR → commit
    ├── Task 2: RED → GREEN → REFACTOR → commit
    ├── Task N: ... → commit
    │
    └── Closing: checkpoint (write) → fresh subagent resumes → publish-pr → PR ready
    │
/pair-process-review #pr-number
    │
    ├── Approved → merge → status cascade
    └── Changes requested → fix → re-review
    │
/pair-next → suggests next story

This loop repeats for every story. /pair-next always knows what comes next.

Every skill named here is in the Skills catalog; every how-to in the Guidelines and how-to catalog.

Next: Analysis and refinement workflow, the first workflow that runs on top of the phases.