dev-recap-docs

After a code phase wraps up, review the completed code plus the development process and produce documentation that helps readers understand the runtime flow or self-check the logic. This skill provides a general methodology — applicable to any feature, milestone, or bug fix once development concludes. Stack-specific practice cases may sit in an appendix as "practice references," but they are not the methodology itself.

When to use

Trigger this skill when:

• A feature or phase just finished and a teammate who was not involved needs to understand how the code runs
• You want to review and self-check the logic before forgetting it — verifying correctness and looking for missed edge cases
• Integration hit a series of pitfalls and you want to capture "symptom → root cause → fix" so they are not hit again
• The code no longer matches the old docs and you need to regenerate, treating the code as the source of truth

When NOT to use

• Do not use for prospective guidance. When the user is at a decision point and wants a guide + manual that teaches how to implement something, that is guide-and-manual (prospective, teaches writing). This skill is retrospective — it produces understanding and self-check docs after the code exists.
• Do not use for software-engineering diagrams from source. When the user only wants flow / sequence / class diagrams extracted from code, use code-to-doc instead.
• Do not use to fix bugs surfaced during self-check. If self-checking exposes a real code bug, hand off to error-handling for the fix flow; this skill documents, it does not modify code.

The essential contrast with guide-and-manual: that one is before — at decision time it produces a guide + manual that teaches others how to implement. This skill is after — once implementation is complete it reviews code plus process to produce docs that aid understanding of the runtime, self-check the logic, and record measured pitfalls. The two are complementary: prospective teaches writing, retrospective teaches checking.

Outputs (3 types — pick as needed or produce the full set)

Produce any of the three independently or as a set. The data-flow doc is the core (it teaches understanding and supports self-check at the same time).

Methodology (6 principles, general)

1. Survey the current state — gather enough material before writing, do not rely on impressions

Documentation quality is bounded by its inputs. Before writing, collect:

• Code: entry points (which method / button / event triggers), core classes, the main data-flow spine, state machines, key branches
• Change records: git log / git diff (which files this phase touched and why)
• Dev-process traces: debug logs, pitfall notes, decision discussions
• Existing docs: related decision docs and design docs (cross-check, flag differences)

When material is missing, mark it ⚠️ to fill in rather than fabricating — invented detail is the fastest way to make these docs actively misleading.

2. Dual-audience perspective — write for "understanding" and "self-check" at the same time

For each passage, ask two questions:

• Can a newcomer follow it? (runtime flow clear, design rationale explained, concepts sharp)
• Can the author self-check against it? (logic correct, boundaries covered, nothing missed)

The data-flow doc naturally serves both: the step-by-step breakdown teaches understanding (how it runs) and supports self-check (is each step right) at the same time.

3. Break the data flow down step by step — the core method

Pick one end-to-end complete path (e.g. "user taps connect → connection succeeds") and break it down from entry to exit:

trigger → step ① → step ② → ... → done

Each step carries 5 elements (omitting any of them leaves a gap a reader can fall through):

1. Code location: file:line or class.method (clickable so the reader can jump and verify)
2. Action: what this step does (one sentence)
3. Data flow: what comes in, what goes out, sent where / received from where
4. Expected behavior: what logcat / terminal / UI should show (concrete — writing "should succeed" gives the reader nothing to match against)
5. Checkpoint: what counts as right for this step, what counts as wrong

Append at the end:

• Overview diagram (ASCII / Mermaid, marking each step plus data-flow direction)
• Stall analysis: if this step stalls, the likely causes and how to locate them (this is the highest-value part in practice)
• Peer / external dependencies: what external conditions this step relies on (other systems / teams / configs)

4. Categorize the self-check list — do not skip dimensions

Categorize the logic self-check by dimension, with each item independently verifiable (✓ pass / ✗ problem / ⚠️ to verify):

5. Measured pitfalls — record only what was actually hit, thread the numbers across the doc

The pitfalls list collects only pitfalls actually hit during development (with symptom / log evidence). Do not invent "theoretically possible" pitfalls — they crowd out the real ones and erode the reader's trust in the rest of the list. Each entry carries:

• Number (#1, #2...; consistent across the doc; code comments can cite pitfall #N)
• Symptom: the error or abnormal behavior (paste the measured log fragment)
• Root cause: why this happens (the underlying reason, not the surface symptom)
• Fix: how it was resolved (what was changed in code)
• Code location / phase: which file / phase it corresponds to

A measured pitfall is far more valuable than a theoretical one — it is "an error someone actually made," not "an error someone imagined might be made."

6. Treat code as the single source of truth — when doc and code disagree, code wins

The worst failure mode of retrospective docs is "the doc says A but the code is B." While generating:

• Make every description traceable to specific code (file:line)
• When you find a contradiction between doc (including your own earlier docs) and code, fix the doc, not the code (unless the code is itself a bug), and flag the difference
• Extract facts like state, fields, and signatures from the code rather than from memory — memory drifts and silently corrupts the doc

Step one: pick a path and survey the current state

1. Confirm with the user which path / feature to document (e.g. "connection establishment flow", "network provisioning flow", "the fix for bug X")
2. Read the code to map the main spine: entry → core classes → data flow → state → output
3. Read git log / session memory to find pitfalls and decisions
4. Tell the user what material was found and what is missing before writing

Templates

Template A: data-flow self-check doc

# {Feature} data flow (debug checklist)

> Helps understand the runtime flow and self-check the logic. Cross-check step by step against logcat.

## 1. Overview diagram
[ASCII / Mermaid data-flow diagram: trigger → each step → done, with data-flow direction marked]

## 2. Step-by-step breakdown (code + data + expected + checkpoint)

### ① {Step name}
- **Code**: `file:line` / `class.method`
- **Action**: what it does
- **Data**: input / output / send-receive direction
- **Expected log**: concrete output
- **Checkpoint**: what counts as right

### ② ... (repeat)

## 3. Stall analysis
For each step, the likely causes if it stalls + how to locate them (this is the highest-value part in practice)

## 4. Peer / external dependencies
What external conditions this flow relies on (other systems / teams / configs / protocol alignment)

## 5. Current status (measured)
Which steps now pass and which still stall (attach a measured logcat summary)

Template B: logic self-check list

# {Feature} logic self-check list

| Dimension | Check item | Status | Notes |
|-----------|-----------|--------|-------|
| Correctness | Main-flow XX logic | ✓ / ✗ / ⚠️ | |
| Boundaries | Null / concurrency / repeats | | |
| Exceptions | Failure paths / resource cleanup / timeout | | |
| Timing | A after B / callback thread / race | | |
| Resources | Connection / handle release | | |
| Constraints | Follows project DI / error / logging conventions | | |

Template C: measured pitfalls list

# {Feature} measured pitfalls list

| # | Symptom (log) | Root cause | Fix | Code location |
|---|---------------|------------|-----|---------------|
| 1 | `Unresolved reference 'X'` | Legacy DTO missing field | Add field to DTO + import | SignalingMessage.kt |
| 2 | `password empty` | PKCS12 password empty | Non-empty password + openssl -legacy | MqttTlsConfig.kt |
| ... | | | | |

Constraints and red lines

1. Do not write from impression. Every description (API signature, field, state, constant) comes from code or measured log; do not fill gaps with generic knowledge — fabricated detail is what makes retrospective docs actively harmful.
2. Do not write only the happy path. The data flow has to include failure / timeout / exception branches; the stall analysis is the core value of the doc, not an afterthought.
3. Do not invent pitfalls. The pitfalls list collects only ones actually hit (with symptom evidence); theoretical pitfalls dilute the list and mislead readers about real risk.
4. Do not let docs drift behind code. When you find a contradiction, fix the doc (and flag the difference) — treating stale docs as authoritative is how code and docs silently diverge.
5. Do not break existing abstractions. The doc describes the code as it is; do not modify the code through documentation (unless the user confirms the discrepancy is a bug).
6. Code locations are clickable. file:line or class.method, so the reader can jump and verify each claim.

Practice references (optional, as appendix)

The methodology itself is fully general. If the project already has a successful "dev-wrap-up documentation" practice, you may cite it as an appendix example — but the methodology does not depend on any specific tech stack or scenario. When generating docs for another feature or scenario, apply the same methodology and templates.

Follow-up actions after completion (suggest to the user; do not run automatically)

• Run the readme-sync skill to check whether the project's onboarding / getting-started docs need syncing
• If self-check surfaces a code bug, run the error-handling skill to drive the fix flow
• If a pitfall is important, consider sinking it into CLAUDE.md or the relevant decision doc (via the change-recap skill)