project-doc

Project Doc

Why This Exists

Every task is an opportunity to learn something or repeat a past mistake. This skill ensures three things:

1. You read before you act. The repo has accumulated knowledge in docs/. Ignoring it means rediscovering problems that were already solved.
2. The human approves before you execute. This is an async workflow — the human needs to see and approve the plan before work begins.
3. What happened gets recorded. After execution, the doc captures what worked, what didn't, and what to remember next time.

When To Use

Use this skill when the user gives a task that involves doing something — writing code, running commands, debugging, deploying, refactoring, setting up, fixing, creating, modifying, testing, or investigating.

Do not use it for:

• Pure questions ("what does this function do?")
• Casual discussion or brainstorming with no action item
• Continuing work on a task that already has an active project doc open in context

When in doubt, use it. An unnecessary project doc costs a minute. A missed one costs repeated mistakes.

Lifecycle

Prepare → Review Gate → Execute → Debrief

You must not skip phases or combine them. Each phase ends with a clear handoff to the user.

---

Phase 1: Prepare

1.1 Read the index

Read docs/index.md. Every time, no exceptions. Use it to identify which other documents are relevant to this task.

1.2 Read relevant docs

Based on the index, read the minimal set of documents that could inform this task. Think about:

• Is there a doc about the model line or subsystem being touched (docs/models/<line>/, docs/subsystems/<area>/)?
• Is there a relevant playbook or lesson (docs/playbooks/, docs/lessons/)?
• Is there a past task doc on similar work in the same domain directory?
• If writing code or scripts, are there existing implementations to learn from?

Be honest about what you read. Only list files you actually opened.

1.3 Find or create the task doc

Decide where the doc belongs using the classification rule in CLAUDE.md (model line / subsystem / playbook / lesson / benchmark / roadmap). If a doc in that directory already covers this task, reuse it.

• Exists and active → reuse it, update the Preparation section.
• Nothing matches → create a new file with a descriptive slug in the appropriate directory. Examples:
  • docs/models/qwen35/fix-decode-state-leak.md
  • docs/subsystems/scheduler/chunked-prefill.md
  • docs/playbooks/nsys-trace-collection.md

1.4 Write the Preparation section

## Preparation

- **Read**:
  - `path/to/doc` — what it told us
  - `path/to/doc` — what it told us
- **Relevant history**:
  - `docs/<domain>/past-task.md` — learned that X causes Y
  - (or: no relevant past docs found)
- **Plan**:
  1. Concrete step with specifics (files, commands, resources)
  2. Concrete step
  3. Concrete step
- **Risks / open questions**:
  - What could go wrong or what's still unknown
  - (omit section if genuinely none)

Rules:

• Read — only files you actually opened. No padding.
• Relevant history — past project docs, known pitfalls, lessons learned. This is how you avoid repeating mistakes. Look for them.
• Plan — concrete and specific. "Investigate the issue" is not a plan step. How will you investigate? What will you look at? What commands will you run?
• Risks — if something might go wrong or you're unsure about something, say so now. It's much cheaper to catch it here than during execution.

1.5 Stop and ask for review

Present a short summary and explicitly ask the user to approve before you do anything.

Format:

? Task doc: `docs/<domain>/<name>.md`

Read:
- `docs/index.md`
- `<other files>`

Plan:
1. ...
2. ...

Risks: <one-liner or "none identified">

Please review before I start.

Do not proceed until the user explicitly approves.

---

Phase 2: Execute

Once approved, do the work. As you go, maintain an execution log in the project doc:

## Execution Log

### Step 1: <what you planned>
- What you actually did
- Commands run, files modified
- Result: success / partial / failed

### Step 2: ...

### Unexpected
- Anything that surprised you or deviated from the plan
- Errors encountered and how you resolved them
- Things that were harder or easier than expected

Rules:

• Log as you go, not after the fact.
• Be specific: include actual error messages, actual file paths, actual command output (abbreviated if very long).
• If you deviate from the plan, note why.
• If you hit a problem that blocks progress, stop and ask the user rather than guessing.

---

Phase 3: Debrief

After execution is complete (or if you're blocked and stopping), write the debrief section:

## Debrief

- **Outcome**: What was accomplished (or not)
- **Pitfalls encountered**:
  - What went wrong or was unexpectedly tricky
  - Root cause if known
- **Lessons learned**:
  - What should be remembered for next time
  - What docs should be updated
- **Follow-ups**:
  - Any remaining work or related tasks
  - (omit if none)

This is the most important section for long-term value. A project doc without a debrief is just a to-do list. The debrief is what prevents the same mistake from happening twice.

Present the debrief to the user as a summary when the task is done.

---

File Template

When creating a new task doc, use this structure:

# <Task Title>

> **TL;DR:** One-line summary. Keep it true as the task progresses — that's
> the only thing readers can rely on.
>
> **Last touched:** YYYY-MM   <!-- only for docs/models/ and docs/subsystems/ -->

## Preparation

(filled in Phase 1)

## Execution Log

(filled in Phase 2)

## Debrief

(filled in Phase 3)

Update the TL;DR whenever the headline state of the work changes. Bump Last touched when you do real work on the doc (skip it for typo fixes). Add a new row to docs/index.md when creating the doc; only update an existing row if its TL;DR has become actively misleading.

---

Principles

• Read first, act second. The cost of reading a doc is minutes. The cost of not reading it is hours of debugging something already solved.
• Be honest about what you don't know. Flagging uncertainty in Preparation is a feature, not a weakness.
• Log the ugly parts. The errors, the wrong turns, the surprises — these are the most valuable things to record.
• The debrief is not optional. Even for tasks that went smoothly, write one. "Everything went as planned, no issues" is a valid debrief. But write it.