impl-note

name	impl-note
description	Use when the user is about to implement a non-trivial feature, refactor, or architectural change. Enforces the "impl-note" pattern with stateful lifecycle management (draft → pending → working → done).

impl-note Development Pattern

A lightweight design-document workflow that prevents "coding by exploration" and makes architectural decisions traceable. Documents have a lifecycle: they are drafted, reviewed, revised, and eventually completed.

When to Trigger

Use this skill before writing any production code when the task involves:

• Architecture changes (new modules, layer rewrites, database migrations)
• Technology selection (evaluating libraries, switching backends, choosing protocols)
• Large-scale refactoring (replacing an ORM, rewriting a data pipeline, restructuring crates)
• Performance-critical paths (where algorithmic or storage choices matter)
• Anything the user explicitly labels as "plan", "design", or "architecture"

Do NOT use for:

• Bug fixes with a clear, localized root cause
• Adding a single endpoint or field
• Style / formatting changes
• Documentation-only updates

Document Lifecycle

Every impl-note goes through four states. The state is declared in the document's frontmatter:

---
status: draft
---

📝 draft — 草稿

The document is a work-in-progress. Facts may be incomplete, trade-offs unexplored, sections missing. The goal is to get a coherent first version on the page.

Your behavior:

• Gather context, read existing code, and write the initial analysis.
• All modifications during the draft phase are applied directly to the document body. Do not append revision history, change logs, or discussion transcripts. The document should always read as a single, coherent description of the current design.
• Do not ask for approval yet; instead, present a rough draft and invite corrections.
• Example prompt: "Here's a first draft of the impl-note for <topic>. Some sections are incomplete—let me know what's wrong or missing before I refine it."

Transitions:

• draft → draft (user asks for changes → rewrite sections in-place)
• draft → pending (user is satisfied with the draft → mark as pending)

📋 pending — 待确认

The document is structurally complete and the user is expected to read it, challenge assumptions, and either approve or request changes.

⚠️ CRITICAL RULE: While the document is in pending status, you must NOT write any production code, create new source files, or modify existing source files. You may only edit the impl-note document itself in response to user feedback. Any code changes require an explicit user approval to transition to working.

Your behavior:

• Present the full document clearly.
• Explicitly ask for confirmation: "Does this plan look correct? Feel free to request changes to any section before I start coding."
• Wait for the user's signal. Do not proceed to working without an explicit go-ahead.
• If the user asks you to start implementing, explicitly confirm: "I'll mark this as working and begin Phase 1. Is that correct?"

Transitions:

• pending → draft (user says "change X" → update document, revert status to draft)
• pending → working (user says "LGTM / looks good / go ahead" → 先检查 git 状态，详见下方 Implement 章节)

🔨 working — 实施中

The plan is approved. You execute the migration plan phase-by-phase.

Your behavior:

• Implement one phase at a time.
• Update the "File Change Checklist" in the impl-note as you go (check off completed items).
• If you discover that the plan is wrong mid-flight, stop and update the relevant sections in-place, then ask the user whether to return to draft or adjust in-place. Do not append revision history.
• After finishing all phases, mark status as done.

Transitions:

• working → draft (fundamental design flaw discovered → rewrite plan)
• working → done (all phases complete, code committed)

✅ done — 已完成

All phases are finished, the code is committed, and the document now serves as a historical record.

Your behavior:

• Append a short "Outcome" section summarizing what actually shipped vs. what was planned.
• Commit the final version of the impl-note.
• No further transitions; the document is read-only history.

---

State Machine Diagram

        ┌─────────────────────────────────────┐
        │                                     │
        ▼                                     │
   ┌─────────┐    "修改"     ┌─────────┐     │
   │  draft  │◄─────────────│ pending │     │
   │  (📝)   │              │  (📋)   │     │
   └────┬────┘              └────┬────┘     │
        │                        │          │
   "继续完善"                  "确认通过"     │
        │                        │          │
        │                        ▼          │
        │                   ┌─────────┐     │
        │                   │ working │     │
        │                   │  (🔨)   │     │
        │                   └────┬────┘     │
        │                        │          │
        │                   "发现问题"       │
        │                        │          │
        └────────────────────────┘          │
                                 │          │
                                 ▼          │
                            ┌─────────┐     │
                            │   done  │─────┘
                            │  (✅)   │  "作为参考"
                            └─────────┘

---

Workflow

1. Gather Context

Before drafting, investigate the current codebase:

• git log --oneline -10 — understand recent direction
• git diff HEAD~5..HEAD --stat — see what changed recently
• List relevant source files (find src -name "*.rs" or equivalent)
• Read the files that will be affected
• Check existing docs/impl-note/ for prior art

2. Write the Document (status: draft)

Create docs/impl-note/YYYY-MM-DD-<kebab-case-topic>.md.

Naming: date prefix guarantees chronological order in file explorers.

Front matter:

---
status: draft
---

Front matter 只放 status。日期、背景、关联文档等属于内容，放在正文开头更自然。

正文开头格式：

# Title

> **目标**：一句话概括这个 impl-note 要解决什么
> 
> 这里是综合了背景、考量、期望的一段话。说明：
> - **背景**：为什么需要做这个变更（现状痛点）
> - **考量**：做了哪些权衡、选择了什么、放弃了什么
> - **期望**：期望达到什么效果（验收标准或成功指标）
> 
> **关联文档**：`docs/foo.md`、`docs/bar.md`

状态提示（放在正文开头，随状态变化）：

状态	正文开头提示
draft	> **状态**：📝 draft — 草稿，正在完善
pending	> **状态**：📋 pending — 待确认，等待用户审核
working	> **状态**：🔨 working — 已确认，正在实施
done	> **状态**：✅ done — 已完成

---

1. Current State Analysis

• What exists today?
• What are the pain points?
• Relevant code paths / files

2. Goals & Non-Goals

Goals	Non-Goals (out of scope)
...	...

3. Proposed Architecture

• Module / crate layout
• Data flow diagrams (ASCII is fine)
• Key abstractions and their responsibilities

4. Detailed Design

For each new or changed component:

• Interface / API surface
• Data structures
• Error handling strategy
• Concurrency model (if applicable)

5. Migration Plan

Break into phases with clear exit criteria:

1. Phase 1: ... (priority: high)
2. Phase 2: ... (priority: high)
3. Phase 3: ... (priority: medium)

6. Risks & Open Questions

Risk	Mitigation
...	...

7. File Change Checklist

Status	Action	Path	Notes
[ ]	Create	src/foo.rs	...
[ ]	Modify	src/bar.rs	...
[ ]	Delete	src/old/	...

### 3. Iterate with the User (status: draft ↔ pending)

- Present the draft, invite corrections.
- When the user is satisfied, update frontmatter to `status: pending` and ask for final approval.
- If the user requests changes after `pending`, revert to `status: draft`, rewrite the relevant sections in-place, then go back to `pending`. Do **not** append revision history.

### 4. Implement (status: working)

Only after explicit user approval (`pending → working`).

**开始执行前必须执行的 git 检查：**

1. **检查 impl-note 文档是否已 commit**：
   - 运行 `git status` 查看 `docs/impl-note/YYYY-MM-DD-*.md` 是否在暂存区或已提交
   - **如果未 commit**：提示用户先提交文档，例如：
     > "impl-note 文档尚未提交到 git。建议先执行 `git add docs/impl-note/xxx.md && git commit -m 'docs: add impl-note for xxx'` 后再开始实施。是否仍要继续？"

2. **检查工作目录是否干净**：
   - 运行 `git status --short` 查看是否有未暂存的改动
   - **如果工作目录不干净**（存在 `??` 未跟踪文件或 `M`/`D` 修改）：
     - 提示用户当前工作目录有未提交的改动，列出受影响的文件
     - 询问用户是否继续实施，或建议先 stash/commit
     - 例如：
       > "检测到工作目录有未提交的改动（列出文件）。建议先提交或 stash 后再开始实施，避免与重构代码混合。是否仍要继续？"

3. **如果用户确认继续**：
   - 将文档状态更新为 `working`
   - 开始按阶段实施

**实施过程中的行为**：
- Proceed phase by phase.
- Check off items in the "File Change Checklist" as you go.
- If the plan changes mid-flight, update the relevant sections in-place and ask the user whether to return to `draft`. Do **not** append revision history.

### 5. Complete (status: done)

After all phases are done:
- Append an **Outcome** section summarizing what actually shipped.
- Update frontmatter to `status: done`.
- Commit the final note alongside the implementation.

---

## Example Trigger Phrases

Watch for these from the user:

- "I want to switch to X" / "migrate to Y"
- "How should we architect this?"
- "Let's plan the refactor"
- "Design the new module"
- "What's the best way to implement Z?"
- Any mention of "orm", "database", "backend switch", "rewrite", "restructure"

## Benefits

- **Traceability**: Six months later, `git log docs/impl-note/` tells you *why* a decision was made.
- **Scope control**: Writing forces you to define "non-goals" before scope creep happens.
- **Collaboration**: Stakeholders can review a markdown file faster than a diff.
- **Onboarding**: New developers read `docs/impl-note/` to understand the system's evolution.
- **Stateful tracking**: Status prevents premature implementation and records the evolution of the plan.

## Related Conventions

- `docs/AGENTS.md` — Project-wide conventions and external resources
- `docs/impl-note/` — Chronological archive of all architectural decisions
- `docs/duckdb-guide.md` — Example of a technology-specific guide (referenced by impl-notes)