aes-docs

Purpose: Route every claim to the correct document, and ensure every public code item is documented. Audience: The AI agent executing documentation tasks. Scope: Python, Rust, and TypeScript modules; PRD, ROADMAP, FRD, README, BACKLOG, DESIGN, and AGENTS files.

The aggregate defines which document exists, where it lives, who reads it, and which claim belongs where. Templates, section contracts, exemplars, and per-document craft rules live in references/.

Code surface (doc comments) — same Rules / Template / Section Contract / Verify shape:

The Document Chain:
PRD → ROADMAP → FRD → BACKLOG → README→ AGENTS

Each file answers exactly one audience's question. A claim in the wrong file is the defect this skill exists to prevent. Doc comments on every public item are the sixth deliverable, in the language's native form.

Invariants

Every rule is machine-checked by lint-arwaky-cli docs (crate doc-rules, AES601–AES605). A rule cannot drift from the gate. Cite the code, not this file, when pointing at a rule. Each document's required section set is cross-checked against its reference's contract table, so a row that stops being enforced is a test failure rather than a silent edit.

Unchecked Invariants (Language Rules)

The checker cannot parse code intent. Enforce these manually (contracts live in the language refs above):

• Doc comments explain what and why, never how (the code shows how).
• Python: Public classes and functions need docstrings (PEP 257) — references/HOW-TO-MAKE-PYTHON-DOC.md.
• Rust: Public items need /// (plain // is invisible to cargo doc). Examples must compile — references/HOW-TO-MAKE-RUST-DOC.md.
• TypeScript: Public items need JSDoc — references/HOW-TO-MAKE-TYPESCRIPT-DOC.md.

Diagnostic Tree

Ask these questions in order. The first "No" dictates your next action.

1. Can a stakeholder understand this project's purpose in 30 seconds?
   • No → Add PRD.md (what/why).
2. Can a tech lead see every feature, shared policy, and workspace truth in one place?
   • No → Add ROADMAP.md (index, definitions, status policy, roll-up, risk).
3. Can an engineer implement this from the spec alone?
   • No → Add FRD.md (how).
4. Can a reader tell what is actually true today for one feature, and re-run the evidence?
   • No → Add BACKLOG.md beside that feature's spec.
5. Can a developer clone, build, and run in under 10 minutes?
   • No → Add README.md (how to use).
6. Can an agent work here safely without being told twice?
   • No → Add AGENTS.md (how to work here).
7. Can a new engineer tell which layer a file belongs in, and what it may import?
   • No → Add ARCHITECTURE.md (layer boundaries).
8. Can a first-time contributor set up the project and open a passing PR?
   • No → Add CONTRIBUTING.md (how to ship a change).

Repository Layout

project-root/
├── PRD.md          # stakeholder alignment (what/why) — 1 per project
├── ROADMAP.md      # feature index, shared policy, workspace condition — 1 per project
├── README.md       # developer onboarding (how to use) — 1 per project
├── AGENTS.md       # operational guide (how the agent works here) — 1 per project
├── ARCHITECTURE.md # layer boundaries and allowed dependencies — 1 per project
├── CONTRIBUTING.md # contributor setup, contribution paths, PR gates — 1 per project
├── DESIGN.md       # visual & interaction contract (optional theme) — 1 per project
├── crates|modules|packages/
│   ├── feature-a/
│   │   ├── src/
│   │   ├── FRD.md     # engineering specs (how) — per feature crate
│   │   └── BACKLOG.md # feature real condition — beside its spec
│   ├── feature-b/
│   │   ├── src/
│   │   ├── FRD.md
│   │   └── BACKLOG.md
│   └── shared/        # kernel — NO FRD.md / BACKLOG.md (feature-doc-in-shared)

```text

Same shape for Python `modules/<feature>/` and TypeScript `packages/<feature>/`.
Cross-cutting rows live in the root master `ROADMAP.md` (legacy root `BACKLOG.md` still accepted), not in a feature backlog.

---

## Workflow

1. **Resolve the repo-root anchor first.** `lint-arwaky-cli docs` 
2. **Analyze**: List feature modules and public items. Run `lint-arwaky-cli docs <path>`. The findings are your work list.
3. **Draft PRD**: Write root `PRD.md` per [references/HOW-TO-MAKE-PRD.md](references/HOW-TO-MAKE-PRD.md).
4. **Draft Roadmap**: Write root `ROADMAP.md` per [references/HOW-TO-MAKE-ROADMAP.md](references/HOW-TO-MAKE-ROADMAP.md)
5. **Draft FRDs**: Write `FRD.md` in each feature dir per [references/HOW-TO-MAKE-FRD.md](references/HOW-TO-MAKE-FRD.md).
6. **Draft Feature Backlogs**: Write one `BACKLOG.md` per feature, beside its spec, per [references/HOW-TO-MAKE-BACKLOG.md](references/HOW-TO-MAKE-BACKLOG.md).
7. **Draft README**: Write root `README.md` per [references/HOW-TO-MAKE-README.md](references/HOW-TO-MAKE-README.md).
8. **Draft AGENTS**: Write root `AGENTS.md` per [references/HOW-TO-MAKE-AGENTS.md](references/HOW-TO-MAKE-AGENTS.md).
9. **Draft ARCHITECTURE**: Write root `ARCHITECTURE.md` per [references/HOW-TO-MAKE-ARCHITECTURE.md](references/HOW-TO-MAKE-ARCHITECTURE.md) — required when the workspace has more than one layer beyond shared.
10. **Draft CONTRIBUTING**: Write root `CONTRIBUTING.md` per [references/HOW-TO-MAKE-CONTRIBUTING.md](references/HOW-TO-MAKE-CONTRIBUTING.md) — required when the repo accepts external contributions. One section per contribution path the project actually supports; delete the rest.
11. **Draft DESIGN**: Write root `DESIGN.md` per [references/HOW-TO-MAKE-DESIGN.md](references/HOW-TO-MAKE-DESIGN.md) — optional; create it when the surface exposes visual tokens (colors, type scale, component anatomy).
12. **Document Code**: Add doc comments to all public items per language —
   [references/HOW-TO-MAKE-PYTHON-DOC.md](references/HOW-TO-MAKE-PYTHON-DOC.md),
   [references/HOW-TO-MAKE-RUST-DOC.md](references/HOW-TO-MAKE-RUST-DOC.md),
   [references/HOW-TO-MAKE-TYPESCRIPT-DOC.md](references/HOW-TO-MAKE-TYPESCRIPT-DOC.md) —
   then add type annotations to all signatures.
13. **Verify**: Run `lint-arwaky-cli docs <path>`. Then each touched reference's `Verify` block (including the language doc ref).

---

## Verification

### Machine Checks

```bash
lint-arwaky-cli docs .                 # invariant audit of every document (strict; every finding gates)

A pass means no claim sits in the wrong file, no pointer is broken, and no Done row is unevidenced.

Human Checks

A machine pass does not mean the documents are good. Falsifiable goals, honest exclusions, and a 10-minute Quick Start still need a reader.

Doc Comment Conventions

Per-language rules, templates, section contracts, and Verify blocks:

• Python (PEP 257): references/HOW-TO-MAKE-PYTHON-DOC.md
• Rust (/// / rustdoc): references/HOW-TO-MAKE-RUST-DOC.md
• TypeScript (JSDoc / TSDoc): references/HOW-TO-MAKE-TYPESCRIPT-DOC.md

Pre-flight Checklist

• lint-arwaky-cli docs <path> exits 0.
• Every required document exists in the correct directory.
• Every Done backlog row cites a re-run command, a commit hash, and its exclusions.
• Documents serve their exact audience (no cross-contamination).
• Public code items carry doc comments, and surface checks (cargo doc, tsc, import) are clean.
• Every touched reference file had its specific Verify block executed.

Common Mistakes (Anti-Patterns)

The invariant codes above cover the machine-checkable ones. These need a reader:

Structural

• One document for all audiences: Split by audience. Each file answers one question.
• FRD at the project root: It belongs with the feature code, beside its backlog.
• Feature backlog carrying workspace rows or restating root policy: Cross-cutting rows and State/Health definitions live once in ROADMAP.md (root master).
• PRD carrying SQL schemas or API detail: The PRD audience cannot read them. Move to FRD.

Cadence and code surface

• Documents "write & forget": Re-run lint-arwaky-cli docs each sprint. Drift is silent.
• // instead of /// in Rust: Plain comments are invisible to the doc generator.
• Missing module docstrings or undocumented parameters: The generated API surface stays incomplete.

Checker false-freights to dodge when authoring specs (these bite at draft time, before you run the gate):

• The word "implemented" in a spec file. status-in-spec matches \b(impl|un)plemented\b case-insensitively across the whole FRD/PRD — so the reference template's | As Implemented / As Intended | column and any implemented cell header/cell are auto-flagged. Name the column impl / intended and use impl for the cell. (Same class: shipped/released in v…, checkbox items, status markers checkmark / cross status markers, progress % all trip it.)
• Scenario-evidence rows without a table header. check_scenarios counts evidence via a markdown-table parser that needs a | Scenario | … | header + |---| separator line; a headerless block of | … | rows parses as 0 rows and reports 0 evidence row(s) even when the rows are present. Always emit the header row; keep exactly one row per spec scenario, in spec order.
• Scenario bullets containing <. The scenario counter skips any spec bullet whose text contains < (placeholder convention), so that scenario needs no evidence row — don't write one, or the count is off by one. Rename <placeholder> prose to avoid the silent skip.

Related Skills

• aes-lint-arwaky
• aes-taxonomy
• aes-contract