/describing-products

name: describing-products
description: >-
  Builds a product description repo for a software product - prose documents
  that say, feature by feature and event by event, what the user sees, what they
  can do, and exactly what happens when they do it, including when they stop
  halfway. Drafted from the code and tests, verified against the running product
  with hand checklists, and triaged into a bug list. Works for canvas editors, web
  apps, CLIs, chat products, mobile apps, and libraries or SDKs. Use when asked to "write a product
  description for X", "describe the user experience of X", "document how X
  behaves for the user", "make a behavior-spec repo", or for an event-by-event
  account of an app's behavior rather than API docs. Also resumes or extends an
  existing product description repo.
metadata:
  version: 0.2.0

Describing products

A product description treats the product as a large state chart the user moves through with input. The repo describes that state chart feature by feature, in plain language, from the user's side, with one skeleton for every document so that gaps and inconsistencies show up by comparison. Documents are drafted from source and tests, verified by hand against the running product, and every suspected defect lands in one triage file.

Adjacent skills: `featuring` inventories what a codebase does, by capability; this skill specifies how each capability behaves under every input and interruption. A `_FEATURES.md` is a good seed for this repo's structure, not a substitute for it.

`{skill}` below is this skill's directory.

| File | Use | | --- | --- | | `references/product-kinds.md` | Map the template onto a canvas editor, web app, CLI, chat product, or library/SDK. Read in Phase 0. | | `references/README-template.md`, `goal-template.md`, `glossary-guide.md` | Skeletons for the three files that steer the build. `goal-template.md` carries the writing rules. | | `references/document-template.md` | The eight-section skeleton every feature document follows. | | `references/verification-template.md`, `bug-triage-template.md` | Skeletons for the checking half. | | `scripts/check_links.py` | Every relative link and heading anchor resolves (GitHub slug rules). Links to documents the coverage table lists as `not started` are reported as planned; `--strict` counts them as broken. | | `scripts/check_structure.py` | Coverage table matches disk; sections in order; footer present; modifier, interrupt and concern rows identical across documents; no empty cells. `--exclude` names extra non-feature files. |

Both scripts are stdlib Python 3, take the repo root, and exit 1 on failure.

Outputs

README.md            purpose, conventions, document template, method, structure, coverage table
goal.md              standing instructions for whoever drafts (you, subagents, a future session)
glossary.md          the vocabulary; source of truth for every term of art
AGENTS.md            "Read README.md, then goal.md. The coverage table in README.md is the work list."
CLAUDE.md            "Read @AGENTS.md."
{area}/{feature}.md  one document per feature, all on the same skeleton
verification/        README.md (protocol) + one checklist file per cluster of documents
bug-triage.md        every suspected defect, deduplicated, with repro, cause, severity, decision needed

Phase 0: scope

Settle these before writing a file. Ask only for what the conversation and the source repo cannot answer; record the answers in the README's "Scope decisions".

1. **Product and surface.** Which app, route, role or configuration, with what customization (usually none). One surface per repo. 2. **Source of truth.** Path to the source repo (read-only) and its commit. Every document footer cites `git rev-parse --short HEAD` of that repo. 3. **Where to run it.** The command and URL, binary, or account that brings the surface up for verification. 4. **Out of scope.** Name each exclusion and why, so readers do not take it for an omission. 5. **Where the repo goes.** A new directory with `git init` and a first commit `Initial commit`, or a directory inside an existing repo when the user keeps such work there (then follow that repo's conventions too, and pass its extra files, such as a `RESULTS.md`, to `check_structure.py --exclude`). 6. **The product's shape.** From `product-kinds.md`, decide once: the unit of interaction and its five phase names; the variant axis; the fixed interrupt list; the cross-cutting concerns and their order. These go into the README's "Document template" and the glossary before the pilot, and do not change afterwards without revisiting every document.

Then reconnoitre the source repo for: where interaction state lives (state machines, reducers, controllers, route handlers, command definitions), the behavior tests that read as executable specs of edge cases, the UI, and where defaults and thresholds are defined. Use `tree-sitting` or `exploring-codebases` for this when available rather than reading files whole. The findings fill the README's "Reference" section and goal.md's reading order.

Phase 1: scaffold

Write, in order, from the templates:

1. **README.md** from `README-template.md`. The structure section is the plan: every expected document with a one-line gloss, grouped by how the user meets the feature (foundations, then the product's areas, then cross-cutting concerns), never by package or module. The coverage table lists every document as `not started`. Revise both as you learn; they must always mirror the files on disk. 2. **glossary.md** from `glossary-guide.md`. Start with the terms the foundations need and the interrupt words from Phase 0. A term used in a document but absent from the glossary is a consistency bug. 3. **goal.md** from `goal-template.md`. It drives all drafting. Its "Things already established" section starts empty. 4. **AGENTS.md** and **CLAUDE.md** with the contents shown under Outputs. AGENTS.md is what a fresh session r