Documentation
Purpose
Produce and maintain documentation of the work — placed canonically, kept concise, and never duplicated. Implements ../../system/DOCUMENTATION_RULES.md.
Scope: everything under .ai/. The applications' own documentation — the docs/ tree with a folder per app and a file per screen, page, endpoint, or job — belongs to application-documentation. Both are needed; neither restates the other.
When to Use
- Recording decisions, project state, work items, knowledge, or reports.
- Updating READMEs/indexes when structure changes.
- Not for documenting the applications themselves — screens, pages, endpoints, jobs go to
application-documentation.
- Not to pad output with narration or restate canonical rules.
Inputs
- The fact/decision/state to document and its canonical home.
- Existing docs that may already cover it.
Discovery Questions
- Is this canonical (
../../system/), project state (../../projects/current/), knowledge (../../knowledge/), or generated (../../generated/)?
- Or is it a fact about the built product? Then it is
docs/, not .ai/ — hand to application-documentation.
- Does a doc already cover this (update vs create)?
- Who reads this next, and what do they need?
Responsibilities
- Place docs in the correct canonical location (see the map in
DOCUMENTATION_RULES.md).
- Keep adapters thin — link to
.ai/, never duplicate it.
- Record decisions and their reasons (including rejected alternatives).
- Keep progress/task notes concise (status, decisions, links).
- Update relevant indexes (e.g.
../README.md) when adding entries.
- Archive stale generated content (
../../generated/).
Required Workflow
- Identify the canonical home.
- Check for an existing doc to update.
- Write concisely; capture the "why."
- Update the relevant index.
- Archive superseded generated docs.
Decision Rules
- Single source of truth: document once, link elsewhere.
- Update over duplicate; delete/correct stale over contradict.
- Generated reports are archivable, not permanent context.
Rules
- No duplication of system rules into adapters or other docs.
- No secrets/unredacted PII in any doc (
../../system/SECURITY_RULES.md).
- Write for reload: self-locating, with links.
Anti-Patterns
- Fat adapters restating the system.
- Verbose progress logs that bury the decision.
- Duplicate docs that drift out of sync.
- Long code examples in permanent skills (use
../../references/ / ../../templates/).
Validation Checklist
Definition of Done
Documentation placed canonically, concise, non-duplicative, with decisions and reasons recorded, indexes updated, and stale generated content archived.
Related Skills
application-documentation (the docs/ half), project-orchestrator, code-review, final-quality-audit, and any skill producing records.
Related Knowledge
../../knowledge/ (where durable knowledge lands).
Related References
../../references/ structure conventions.
Context Loading Guidance
- Requires: the item to document and its canonical home.
- Does not require: unrelated source, the full reference tree, other skills' bodies.
- May load: the target index/README to update.
- Stop when: the doc + index are updated and stale content archived.
Token Efficiency Guidance
Write the minimum that serves the next reader. Link rather than paste. Summarize source into decisions.
1---2name: documentation3description: Use to write or update documentation of the work inside `.ai/` — decisions, project state, work items, knowledge, generated reports — concisely and in its canonical place. For the applications' own documentation (the `docs/` tree), use `application-documentation` instead.4---56# Documentation78## Purpose910Produce and maintain documentation of **the work** — placed canonically, kept concise, and never duplicated. Implements `../../system/DOCUMENTATION_RULES.md`.1112Scope: everything under `.ai/`. The **applications' own documentation** — the `docs/` tree with a folder per app and a file per screen, page, endpoint, or job — belongs to `application-documentation`. Both are needed; neither restates the other.1314## When to Use1516- Recording decisions, project state, work items, knowledge, or reports.17- Updating READMEs/indexes when structure changes.18- **Not** for documenting the applications themselves — screens, pages, endpoints, jobs go to `application-documentation`.19- **Not** to pad output with narration or restate canonical rules.2021## Inputs2223- The fact/decision/state to document and its canonical home.24- Existing docs that may already cover it.2526## Discovery Questions2728- Is this canonical (`../../system/`), project state (`../../projects/current/`), knowledge (`../../knowledge/`), or generated (`../../generated/`)?29- Or is it a fact about the built product? Then it is `docs/`, not `.ai/` — hand to `application-documentation`.30- Does a doc already cover this (update vs create)?31- Who reads this next, and what do they need?3233## Responsibilities3435- Place docs in the **correct canonical location** (see the map in `DOCUMENTATION_RULES.md`).36- Keep **adapters thin** — link to `.ai/`, never duplicate it.37- Record **decisions and their reasons** (including rejected alternatives).38- Keep progress/task notes **concise** (status, decisions, links).39- Update relevant **indexes** (e.g. `../README.md`) when adding entries.40- **Archive** stale generated content (`../../generated/`).4142## Required Workflow43441. Identify the canonical home.452. Check for an existing doc to update.463. Write concisely; capture the "why."474. Update the relevant index.485. Archive superseded generated docs.4950## Decision Rules5152- Single source of truth: document once, link elsewhere.53- Update over duplicate; delete/correct stale over contradict.54- Generated reports are archivable, not permanent context.5556## Rules5758- No duplication of system rules into adapters or other docs.59- No secrets/unredacted PII in any doc (`../../system/SECURITY_RULES.md`).60- Write for reload: self-locating, with links.6162## Anti-Patterns6364- Fat adapters restating the system.65- Verbose progress logs that bury the decision.66- Duplicate docs that drift out of sync.67- Long code examples in permanent skills (use `../../references/` / `../../templates/`).6869## Validation Checklist7071- [ ] Correct canonical location.72- [ ] Concise; decisions + reasons recorded.73- [ ] No duplication of canonical content.74- [ ] Index updated.75- [ ] Stale generated docs archived.76- [ ] No secrets/PII.7778## Definition of Done7980Documentation placed canonically, concise, non-duplicative, with decisions and reasons recorded, indexes updated, and stale generated content archived.8182## Related Skills8384`application-documentation` (the `docs/` half), `project-orchestrator`, `code-review`, `final-quality-audit`, and any skill producing records.8586## Related Knowledge8788`../../knowledge/` (where durable knowledge lands).8990## Related References9192`../../references/` structure conventions.9394## Context Loading Guidance9596- **Requires:** the item to document and its canonical home.97- **Does not require:** unrelated source, the full reference tree, other skills' bodies.98- **May load:** the target index/README to update.99- **Stop when:** the doc + index are updated and stale content archived.100101## Token Efficiency Guidance102103Write the minimum that serves the next reader. Link rather than paste. Summarize source into decisions.
ahtishamshahzad