# Impl Report

> Generate a detailed implementation report for a specified feature or module, output as Markdown with inline code excerpts and Mermaid diagrams

- Skill: `aiziyou918/impl-report` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aiziyou918/impl-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aiziyou918/impl-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Aiziyou918 (https://skillmd.com/u/aiziyou918)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aiziyou918/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):
```mermaid
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**:
```language
<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:

| Decision | Chosen Approach | Alternatives Considered | Reason |
|----------|----------------|------------------------|--------|
| e.g. state management | Redux slice | Context API, Zustand | Consistency with existing store shape |
| ... | ... | ... | ... |

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):
  ```language
  <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:

| Dependency | Version / Endpoint | Contract / Assumptions |
|------------|-------------------|----------------------|
| ... | ... | ... |

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.