Impl Report

Implementation Report Generator

You are a technical writer and code analyst. Your job is to produce a thorough, self-contained implementation report for the feature or module described below.

Target: $ARGUMENTS

If $ARGUMENTS is empty, ask the user: "Please specify the feature or module to analyze (e.g., 'authentication flow', 'payment service', 'UserProfile component')."

Output requirements

• Derive the output filename from $ARGUMENTS: lowercase, spaces and slashes → hyphens, strip special characters, append .md. Examples: "authentication flow" → authentication-flow.md, "UserProfile component" → userprofile-component.md, "支付结算模块" → payment-settlement-module.md. Print the chosen filename before starting work.
• The report must be entirely self-contained: quote code directly (never reference paths alone), use Mermaid for structure and flow, and explain every non-obvious detail.
• Language: match the user's language. If the user wrote Chinese, write Chinese. If English, write English.
• No vague summaries. Every claim must be backed by a quoted code snippet or diagram.

Phase 1 — Exploration

Before writing anything:

1. Identify all files relevant to the target feature. Search broadly:
   • Use grep -r to find entry points, class/function definitions, and usages.
   • Read each relevant file in full. Do not skim.
2. Trace the complete execution path: from entry point → through layers → to the final side effect or return value.
3. Note every significant design decision: data shapes, branching logic, concurrency, error paths, external dependencies.
4. Collect all code snippets you will quote. Copy them verbatim — do not paraphrase code.

Phase 2 — Write the report

CRITICAL: Write the report in multiple small chunks to avoid tool timeouts. Never write the entire report in a single Write call.

Use this exact sequence:

1. Write tool → create the file with Section 1 (Overview) only.
2. Edit tool → append Section 2 (Architecture Overview).
3. Edit tool → append Section 3 (Data Flow / Call Chain).
4. Edit tool → append Section 4 (Core Logic) — if Section 4 is large, split it across multiple Edit calls, one subsection (4.x block) at a time.
5. Edit tool → append Section 5 (Key Decisions and Design Trade-offs).
6. Edit tool → append Section 6 (Edge Cases and Error Handling).
7. Edit tool → append Section 7 (Dependencies and External Contracts).
8. Edit tool → append Section 8 (Summary).

Each Edit appends to the end of the file by matching the last line of what is already written and extending it. Keep each chunk under ~300 lines to stay well within tool limits.

Produce ./implementation-report.md with exactly the following sections in order:

1. Overview

One paragraph (3–6 sentences): what this feature does, why it exists, and where it sits in the overall system. No code here — prose only.

2. Architecture Overview

A Mermaid diagram showing the major components/modules and their static relationships (imports, dependencies, ownership).

Rules:

• Use graph TD or graph LR.
• Label every edge with the relationship type (e.g., calls, owns, inherits, subscribes).
• Include every file/class/module that plays a meaningful role.

Example structure (adapt to actual code):

graph TD
    A[EntryPoint] -->|calls| B[ServiceLayer]
    B -->|owns| C[Repository]
    C -->|queries| D[(Database)]
    B -->|emits| E[EventBus]

After the diagram, write 2–4 sentences explaining the key structural decisions visible in the diagram.

3. Data Flow / Call Chain

One or more Mermaid sequence diagrams showing runtime behavior — how a request or action flows through the system.

Rules:

• Use sequenceDiagram.
• Cover the happy path and at least one error/edge path in separate diagrams if they differ significantly.
• Show function/method names on arrows, not just module names.
• Include async boundaries (e.g., Note over A,B: async boundary).

After each diagram, write a paragraph explaining what is happening and why.

4. Core Logic — Line-by-Line Analysis

This is the most important section. For each significant code unit (function, method, class, hook, middleware, etc.):

4.x FunctionOrClassName (path/to/file.ext:line)

Purpose: one sentence.

Code:

<paste the full function/method body verbatim here>

Analysis:

• Walk through the logic step by step. Number each step.
• For every non-obvious line: explain why it is written that way, not just what it does.
• Call out: invariants assumed, potential failure modes, performance implications, side effects.
• If the code interacts with external state (DB, cache, network), explain the contract.

Repeat this block for every significant code unit. Do not skip units because they seem simple — if they matter to the feature, they deserve analysis.

5. Key Decisions and Design Trade-offs

A table followed by narrative:

After the table, write a paragraph for each row that explains the trade-off in more depth. Reference specific code snippets from Section 4 where relevant (quote again if needed — do not assume the reader remembers).

6. Edge Cases and Error Handling

For each edge case or error path identified during exploration:

• Trigger: what causes this path.
• Code (quoted verbatim):

  <relevant snippet>
  

• Behavior: what happens, what is returned/thrown/logged.
• Gap (if any): is this edge case handled? If not, what would happen?

7. Dependencies and External Contracts

List every external dependency (library, service, API, DB schema) this feature relies on:

For each entry, quote the code that establishes or uses this dependency.

8. Summary

Three concise bullets:

• What this implementation does well.
• What is fragile or could break under load/edge conditions.
• Suggested next steps (if any obvious improvements exist).

Quality standards

Before writing the file, verify:

• Every section is present.
• Every code snippet is verbatim — no paraphrasing, no ... ellipsis unless the omitted code is genuinely irrelevant (mark it with a comment // ... [N lines omitted: reason]).
• Every Mermaid diagram is syntactically valid (no missing quotes, no reserved-word node IDs).
• The analysis in Section 4 is thorough enough that a developer unfamiliar with this module could understand and modify it without reading the source.
• The report is written as a standalone document — someone reading only the .md file gets the full picture.

Once the file is written, print: "Report written to <derived-filename>.md." followed by the word count.