: Plan | Field | Value | | --- | --- | | Status | Planned \| In progress \| Implemented \| Superseded by <link> | | Anchor date | YYYY-MM-DD | | Origin | <who asked, or what triggered the work> | | Related | [NNN-other](../NNN-other/000-plan.md), `docs/...` | ## Background The product problem and its context; for a fix, 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 and files it touches. ## Alternatives & decisions | Choice | Reason and alternative | | --- | --- | Options considered and why the chosen one won. Record decisions, not just designs. ## Validation and acceptance criteria What must be checked, and how (focused tests, simulator run, manual checks). ## Amendments None yet. ``` ### 001-action.md ```markdown # NNN — <Title>: Action record ## Timeline | Date | Change | Ref | | --- | --- | --- | ## Outcome and current state (as of YYYY-MM-DD) What exists in code now, followed by key source files as repo-relative paths. ## Deviations from plan Where reality diverged from 000-plan.md, or "None known." ## Validation Commands and checks actually run, with results. Omit nothing that failed. ## Open questions Unverified claims, oddities worth revisiting, or "None." ``` ### Amendment (002+) ```markdown # NNN.00M — <Topic> ## Context Why this follow-up happened. ## Change What was decided and done, and any rejected alternative. ## Refs Commits, files, tests. Add "## Current state" when useful. ``` ## Writing rules - English, factual, RFC-ish; prefer tables for timelines and decisions. Keep entries long enough to be useful and short enough to be read. - Every repo-relative path you write must exist (verify before writing); label any proposed new path as proposed. Facts you can't verify belong under **Open questions**, not in prose. - Never invent a rationale from code alone. If the reason for a choice is unknown, say so; if you infer it from the implementation, label it as inference. - Do not state build or test results you didn't produce. Old passing tests and checked task lists are not fresh validation. - Reference commits by short hash in backticks; dates come from Git. Cross-link sibling entries with relative links. - Numbered files are history. **Non-numbered** files inside an entry folder (for example `006-.../broadcast-availability-policy.md`, `005-.../requirements/`) are living documents: update them in place when the contract they describe changes, and link them instead of duplicating their content. Files under `historical/` are preserved sources; do not edit them. - A plan reconstructed after the work shipped must say so in its Origin field; never imply it preceded implementation. Such plans add an **Evidence and recovered rationale** section separating source documents, recalled discussion, and inference. - `docs/` holds public tutorials and images; history, decisions, contracts, and runbooks belong in `docs-ai/`. Asset-package READMEs stay with their assets. - AniShelf sources live in `MyAnimeList/Sources/` and `DataProvider/Sources/`. Use `AGENTS.md` for Makefile commands, test filters, simulator rules, and localization.

--- name: write-ai-doc description: Create and maintain curated AniShelf docs-ai/ records for substantial features and non-trivial, decision-shaping fixes (numbered entries with 000-plan.md before implementation and 001-action.md after). Do not use for reviews, audits, routine investigations, working notes, or status reports unless the maintainer explicitly asks for a docs-ai/ record. --- # 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](https://github.com/onevcat/Prowl/blob/main/.claude/skills/write-ai-doc/SKILL.md). 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-/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-.md` (template below). 2. At the end of `000-plan.md`'s **Amendments** section append: `- Updated YYYY-MM-DD: — see [002-.md](002-.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-.md` amendment, starting at `002`. Write `001-action.md` once, when the last slice lands (or the entry is superseded), summarizing the slices. ### 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 `Superseded by [NNN-new-slug](../NNN-new-slug/000-plan.md)`. ## Templates ### 000-plan.md ```markdown # NNN — : Plan | Field | Value | | --- | --- | | Status | Planned \| In progress \| Implemented \| Superseded by <link> | | Anchor date | YYYY-MM-DD | | Origin | <who asked, or what triggered the work> | | Related | [NNN-other](../NNN-other/000-plan.md), `docs/...` | ## Background The product problem and its context; for a fix, 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 and files it touches. ## Alternatives & decisions | Choice | Reason and alternative | | --- | --- | Options considered and why the chosen one won. Record decisions, not just designs. ## Validation and acceptance criteria What must be checked, and how (focused tests, simulator run, manual checks). ## Amendments None yet. ``` ### 001-action.md ```markdown # NNN — <Title>: Action record ## Timeline | Date | Change | Ref | | --- | --- | --- | ## Outcome and current state (as of YYYY-MM-DD) What exists in code now, followed by key source files as repo-relative paths. ## Deviations from plan Where reality diverged from 000-plan.md, or "None known." ## Validation Commands and checks actually run, with results. Omit nothing that failed. ## Open questions Unverified claims, oddities worth revisiting, or "None." ``` ### Amendment (002+) ```markdown # NNN.00M — <Topic> ## Context Why this follow-up happened. ## Change What was decided and done, and any rejected alternative. ## Refs Commits, files, tests. Add "## Current state" when useful. ``` ## Writing rules - English, factual, RFC-ish; prefer tables for timelines and decisions. Keep entries long enough to be useful and short enough to be read. - Every repo-relative path you write must exist (verify before writing); label any proposed new path as proposed. Facts you can't verify belong under **Open questions**, not in prose. - Never invent a rationale from code alone. If the reason for a choice is unknown, say so; if you infer it from the implementation, label it as inference. - Do not state build or test results you didn't produce. Old passing tests and checked task lists are not fresh validation. - Reference commits by short hash in backticks; dates come from Git. Cross-link sibling entries with relative links. - Numbered files are history. **Non-numbered** files inside an entry folder (for example `006-.../broadcast-availability-policy.md`, `005-.../requirements/`) are living documents: update them in place when the contract they describe changes, and link them instead of duplicating their content. Files under `historical/` are preserved sources; do not edit them. - A plan reconstructed after the work shipped must say so in its Origin field; never imply it preceded implementation. Such plans add an **Evidence and recovered rationale** section separating source documents, recalled discussion, and inference. - `docs/` holds public tutorials and images; history, decisions, contracts, and runbooks belong in `docs-ai/`. Asset-package READMEs stay with their assets. - AniShelf sources live in `MyAnimeList/Sources/` and `DataProvider/Sources/`. Use `AGENTS.md` for Makefile commands, test filters, simulator rules, and localization.