create-spec-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# Implementation Retrospective (REVIEW)

You are a tech lead running a retrospective. Your task is to compare the plan with reality and record the results: **$ARGUMENTS**

> **Retrospective = plan vs reality. What was achieved, what diverged, what lessons.**
> This skill does NOT change code — only documentation.


## PHASE 1: Recon (SILENT, no output)

### 1.1. Find the plan

If `$ARGUMENTS` is a file path → read it.
If `$ARGUMENTS` is a name → find it:
```
Glob: docs/plans/*$ARGUMENTS*
```
If not found → show the list: `ls docs/plans/` and let the user pick.

### 1.2. Find the linked spec

Read the `**Specification:**` field in the plan → load the spec from `docs/specs/`.

### 1.3. Find the task tracker

Check TASKS.md — are there entries related to this plan/spec.

### 1.4. Final check of unresolved questions

Read the "Deferred questions" sections in both the plan and the spec. For each entry determine the status:

- **Can be closed now** — implementation gave the answer (it became clear from how the code works in practice) → ask via `AskUserQuestion` to confirm "close as X?" with 2-3 options (see [interactive questions rules](#interactive-questions-rules-shared-block)). After the answer — move to "Decisions".
- **Genuinely still deferred** — the answer is still not needed (e.g. `When the answer is needed` = "v2"). Keep in "Deferred", record it in the retrospective.
- **Should have been closed but was forgotten** — this is **process debt**. Ask the user:
  - option A: close it now (with your recommendation);
  - option B: explicitly carry over to the next cycle (create an entry in TASKS.md / a new spec);
  - option C: mark as "no longer relevant".

Reflect all changes in the plan/spec files **before** generating the retrospective.


## PHASE 2: Implementation analysis (SILENT, no output)

### 2.1. Commits

Find the commits related to implementation:
- By the T-XXX task tag: `git log --oneline --grep="T-XXX"`
- By files from the plan: `git log --oneline -- path/to/file`
- By time range: from the plan's date to now

For key commits — `git show --stat <hash>` to see changed files.

### 2.2. Planned vs actual files

Compare:
- **Planned files** — all `path/to/file` entries from phase checklists
- **Actual files** — files from commits

Determine:
- Which planned files were changed ✅
- Which planned files were NOT touched ❌
- Which files were changed CONTRARY to the plan (unplanned) ⚠️

### 2.3. Checklist status

Walk through every plan phase, count: `[x]` vs `[ ]` per phase.


## PHASE 3: Comparison (SILENT, no output)

### 3.1. Deviations table

For each phase:
- Hour estimate vs actual time (if determinable from commits)
- Planned tasks vs tasks actually done
- Added tasks (not in the plan)
- Skipped tasks (in the plan, not done)

### 3.2. Requirements coverage

By the "Traceability: Requirements → Tasks" table from the plan:
- Which FR-XXX are fully implemented
- Which FR-XXX are partially implemented
- Which FR-XXX are not implemented

### 3.3. Patterns

Identify recurring patterns:
- Systematic under/over-estimates
- Typical causes of deviations (include the plan's `- deviated:` lines logged during implementation)
- Unplanned work — what caused it

### 3.4. Consistency sweep

Cross-check the artifacts before writing the retrospective:
- Spec ↔ plan terminology drift (same entity under different names)?
- Statuses agree (spec criteria ticks vs plan checklists vs TASKS.md)?
- Any principle bent during implementation but never justified in the plan's "Complexity & principle deviations"?
- Brief roadmap: is this feature's item still unticked in `docs/brief/PROJECT-BRIEF.md`?

Findings feed the Lessons/Recommendations sections and Phase 6 updates.


## Interactive questions rules (shared block)

When closing questions via `AskUserQuestion` in Phase 1.4:

- **One question = one tool call** (`questions` array of length 1).
- **2-4 options** + automatic Other.
- **Context in the question**: quote the wording from "Deferred questions" + a brief note of what actually got implemented.
- **Short label** (1-5 words), **description** explains how the answer will affect status and where it will be recorded (in "Decisions", in TASKS.md, or stays deferred).
- **Recommendation** — first option with `(Recommended)`, if the answer is obvious based on the actual implementation.


## PHASE 4: Retrospective generation

Append a new section at the end of the plan file:

From askidmobile/ai-spec-kit, MIT.

More from askidmobile/ai-spec-kit