Write AI Doc

Write AI Doc

docs-ai/ is AniShelf's curated product and design record, not a working-note log. A numbered folder is reserved for a substantial feature or a non-trivial, 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 be selected deliberately and stay accurate against the code. Read docs-ai/README.md for the index before starting.

Adapted from the write-ai-doc skill in onevcat/Prowl. This copy is project-owned: edit it in place, and do not reinstall it from upstream.

When to write one

Create a new entry only when the work is either:

• a substantial feature with an enduring product or architecture decision (for example, a new UI surface, a sync or persistence mechanism, or a schema change);
• a non-trivial fix whose root cause, design decision, or resulting behavior must guide future implementation.

Do not create an entry merely because the work is detailed, takes time, or produces useful findings. Skip reviews, code audits, routine research and debugging, status reports, test runs, minor UI polish, formatting or dependency bumps, and docs-only changes. The maintainer may explicitly request a record for an otherwise non-qualifying task. When in doubt, do not write one.

Workflow

1. New entry — plan first, before coding

1. Check the index for a related entry; an in-frame follow-up belongs there (section 2).
2. Pick the next number: ls docs-ai/ | sort, take the highest NNN + 1 (three digits).
3. Create docs-ai/NNN-<kebab-slug>/000-plan.md from the template below with status Planned. Write it as part of planning, not as an afterthought.
4. Implement the work within the user's authorization. A plan or this skill never authorizes a commit, push, or other remote mutation.
5. Write 001-action.md: what actually happened, chronologically, with commit refs, the resulting key files, validation you actually performed, and deviations from the plan. Flip the plan status to Implemented only when the intended scope is complete; use In progress for partial delivery. When committing is authorized, commit the docs with the change.
6. Add or refresh the entry's row in docs-ai/README.md.

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

1. Add the next-numbered file in the folder, for example 002-<topic>.md (template below).
2. At the end of 000-plan.md's Amendments section append: - Updated YYYY-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.
4. Work delivered in several slices: each slice adds its own 00N-<slice>.md amendment, starting at 002. Write 001-action.md once, when the last slice lands (or the entry is superseded), summarizing the slices.