write-ai-doc git:20260712.b58c831A

Immutable. This exact content never changes and is served at /api/v1/blob/a1ec2f1b0d5faf51.

---
name: write-ai-doc
description: Create and maintain spec-driven work records under docs-ai/ (numbered entries with 000-plan.md before implementation and 001-action.md after). Use when starting a medium/large feature, a complex or decision-shaping fix, or a non-trivial investigation — write the plan entry BEFORE coding; use also when amending an existing entry after follow-up work on the same topic.
---

# Write AI Doc

`docs-ai/` is Prowl's durable record of how the app evolved: one numbered folder per
feature or decision-shaping fix, each holding an RFC-like plan and an action log. Future
humans and agents use it to answer "why is it built this way?" — so entries must stay
accurate against the code. Read `docs-ai/README.md` for the index and intent.

## When to write one

Create a new entry when the work is any of:

- a feature that needs planning (multiple files/reducers, new UI surface, new subsystem);
- a fix whose investigation or decision matters later (root-cause hunts, perf hunts,
  behavior-defining choices, upstream-divergence decisions);
- an investigation worth keeping even if no code changes.

Skip it for: trivial/small fixes, pure formatting or dependency bumps, routine upstream
ports already recorded in the upstream ledger (`docs-ai/017-upstream-sync-process/upstream-ledger.md`), and docs-only changes. When in
doubt, a short entry beats a missing one.

## Workflow

### 1. New entry — plan first, before coding

1. Pick the next number: `ls docs-ai/ | sort` and take highest `NNN` + 1 (three digits).
2. Create `docs-ai/NNN-<kebab-slug>/000-plan.md` from the template below, `Status: Planned`.
   Write it as part of planning — background, goals, approach, alternatives — not as an
   afterthought.
3. Implement the work (normal branch/PR flow).
4. Write `001-action.md`: what actually happened, chronological, with PR/commit refs, the
   resulting key files, and deviations from the plan. Flip plan status to `Implemented`.
   Ship the docs in the same PR as the change when practical.

### 2. Follow-up on an existing entry (in-frame fix or extension)

1. Add the next-numbered file in the folder, e.g. `002-<topic>.md` (template below).
2. At the end of `000-plan.md`'s **Amendments** section append:
   `- Updated 2026-MM-DD: <one line> — see [002-<topic>.md](002-<topic>.md)`.
3. If the follow-up invalidates part of the plan or action text, correct that text in
   place (keep it truthful) and note the correction in the amendment.

### 3. Large pivot / redesign

If the change replaces the entry's approach rather than patching it, open a NEW numbered
entry, cross-link both directions, and mark the old plan `Status: Superseded by
[NNN-new-slug](../NNN-new-slug/000-plan.md)`.

## Templates

### 000-plan.md

```markdown
# NNN — <Title>: Plan

| | |
| --- | --- |
| **Status** | Planned \| Implemented \| Superseded by <link> |
| **Anchor date** | 2026-MM-DD |
| **Primary PRs** | #a, #b (fill in as they merge) |
| **Related** | [NNN-other](../NNN-other/000-plan.md), `docs/...` |

## Background
The problem/pain and its context; for investigations, the observed symptom.

## Goals
Bullets. Add a **Non-goals** subsection when scope exclusion is a real decision.

## Design / Approach
The intended approach; name the key types/files it touches.

## Alternatives & decisions
Options considered and why the chosen one won. Record decisions, not just designs.

## Amendments
(append `- Updated 2026-MM-DD: ... — see [00N-topic.md](00N-topic.md)` lines here)
```

### 001-action.md

```markdown
# NNN — <Title>: Action Log

## Timeline
| Date | Change | Ref |
| --- | --- | --- |

## Outcome & current state (as of 2026-MM-DD)
What exists in code now; key files/types with repo-relative paths.

## Deviations from plan
Where reality diverged from 000-plan.md, or "None known."

## Open questions
Unverified claims, oddities worth revisiting, or "None."
```

### Amendment (002+)

```markdown
# NNN.00M — <Topic>

## Context
Why this follow-up happened.

## Change
What was done. | ## Refs: PR #x | ## Current state (optional)
```

## Writing rules

- English, factual, RFC-ish; prefer tables over prose for timelines. Plans are typically
  40–120 lines, actions 30–100 — long enough to be useful, short enough to be read.
- Every repo-relative file path you write must exist (verify with Glob/Grep before
  writing). Facts you can't verify belong under **Open questions**, not in prose.
- Reference fork PRs as `#123`, upstream PRs as `upstream #123`, files as inline code.
  Cross-link sibling entries with relative links.
- `docs-ai/` is the single home for fork history AND fork-internal operational docs.
  Numbered files are immutable history; **non-numbered** files inside an entry folder
  (e.g. `001-.../release-runbook.md`, `017-.../upstream-ledger.md`,
  `013-prowl-cli/contracts/`, `020-observability/runbook.md`) are living documents —
  update them in place when the process/contract they describe changes, and link them
  instead of duplicating their content.
- `docs/` (the user-facing agent manual) is separate: current behavior goes there,
  history/decisions/runbooks go in docs-ai. Never link `doc-onevcat/` — that directory
  was dissolved into docs-ai in 2026-07.
- The Xcode module/scheme is still `supacode`; `supacode/...` paths are correct.
- After adding or renaming an entry, add/refresh its row in `docs-ai/README.md`'s index.
- Do not state build/test results you didn't produce.