Generate an implementation spec

Generate an implementation spec

Write a spec in specs/ that an engineer can implement without repeating the research. Keep it lean, grounded in the current code, and focused on the requested result.

Research the change

1. Read the request and repository instructions.
2. Find the entry points, key types, state boundaries, callers, tests, and commands tied to the change. Trace each changed runtime path far enough to show an accurate diff.
3. Read external docs only when a dependency or API affects the design. Prefer official docs and record the links used.
4. Ask a question only when the answer would change the result and the code cannot answer it. Otherwise, make the narrowest sound assumption and record it.

Use the amount of research the task needs. Do not impose a fixed research process.

Choose the scope

• Plan the smallest complete change that gives the requested result.
• Do not add abstractions, config, infrastructure, migrations, or cleanup unless the result needs them.
• State goals and non-goals from the request and code. Do not pause for confirmation when the scope is clear.
• Make each phase fit one commit and leave the repository working.
• Use as many phases as the work needs. Do not set a phase or line-count limit.

Write the file

Choose a short kebab-case name and create specs/<name>.md. Use this structure:

# <Feature or fix name>

## System flow

Put one or more Mermaid diagrams immediately after the title, before all prose. Show the main runtime flow and changed parts. Label current and proposed paths or use separate diagrams when that is clearer. Keep node text short and use valid Mermaid syntax.

```mermaid
flowchart TD
    A[Entry point] --> B[Service]
    B --> C[Observable result]
```

## Problem overview