--- name: fbarrento/capability-map source: https://app.decimal.ai/s/fbarrento-capability-map@1/SKILL.md source_sha256: fecd61cdbf51 --- # Capability Map ## What this skill does `capability-map` produces the product's considered capability set — one `README.md` per capability — by decomposing `product/vision.md`. It owns the "is this one capability or three" judgment, and it promotes the provisional capability stubs `change-scope` created during bootstrap into considered capabilities. It produces the decomposition as a PROPOSAL for human approval; on approval it applies the map, migrating the change history of any capability it reshapes. It is the last pipeline skill. ## Where the state tree lives Generic skill — hard-codes no path. Resolve the state-tree root from the project's `CLAUDE.md` (project-declared paths, DESIGN_PRODUCT_PIPELINE.md §2); default `docs/`, and say which you used. `{capabilities-root}` means `{declared-root}/capabilities` (default `docs/capabilities`), and `product/vision.md` means `{declared-root}/product/vision.md`. ## STOP — how this skill works Before producing a capability map you MUST, in order: 1. CHECK THE VISION. Read `product/vision.md`. It must exist and be `status: approved`. If there is no vision, or it is unapproved — STOP. You cannot decompose a product that has not been defined; run `product-vision` first. 2. READ THE CURRENT STATE. Read `vision.md` in full and every existing capability `README.md` (provisional and considered) with its `changes/` history. 3. DECOMPOSE the product into a considered capability set (see "The decomposition"). 4. PRODUCE THE PROPOSAL — the considered map plus every merge / split / rename it implies against the current capabilities (see "The proposal"). 5. SEEK HUMAN APPROVAL of the proposal. Nothing is rewritten before approval. 6. APPLY the approved map (see "Applying the map"), migrating reshaped capabilities. Hard rules: - No vision, no run. The vision is the criterion you decompose against. - You never rewrite a README or a `why-link` before the proposal is approved. - A capability with shipped changes may be reshaped, never erased. Its history is real. ## The decomposition Decompose the product — defined by `vision.md` — into capabilities. A capability is a durable area of the product, named for what it is (`watchlists`), never for a release or version. This is a BATCH judgment over the whole product at once, not a stub-by-stub promotion. Holding the vision and the current capabilities together, decide the considered set. You may conclude: - a provisional stub is sound → promote it as-is; - two provisional capabilities are really one → merge; - one stub should be several → split; - the vision implies a capability nothing has grown toward yet → a new, empty considered capability. Each considered capability cites a vision goal — the goal it serves — as its `why-link`. A capability you cannot tie to a vision goal is a finding: either the vision is incomplete or the capability is misaligned. Surface it in the proposal; do not invent a goal to cite. Most runs the provisional set will be broadly sound and the decomposition mostly confirms it with light edits. Reserve merges and splits for where the decomposition genuinely changes shape. Not every thing in the product is a capability. Some are infrastructure — substrate (DESIGN_PRODUCT_PIPELINE.md §2a): authentication, third-party data feeds, the database. When decomposing, classify each such thing explicitly as infrastructure (not a capability): do NOT invent a vision goal to give it a why-link, and do NOT bury it inside one capability — it sits below the capability layer, consumed directly. If a thing looks like infrastructure but the vision implies users experience it as a product surface, it is a capability and the vision has a gap — flag it, do not misclassify it. ## The proposal Produce the decomposition as a PROPOSAL before changing anything. The proposal states: - the considered capability set, each with its one-line description and the vision goal it cites; - for each existing capability, what happens to it — `confirmed`, `merged into {x}`, `split into {x, y}`, `renamed to {x}`, or `unchanged`; - for every merge / split / rename of a capability that HAS a `changes/` history, the migration it entails — which `changes/` folders move and which `why-link`s must be rewritten; - any capability that cannot be tied to a vision goal, flagged for a human. - any thing classified as infrastructure rather than a capability — listed separately, with no why-link, noted as below the capability layer. Present the proposal for review and explicitly invite rejection or revision. A skill that can mass-break `why-link`s must not act unreviewed. Nothing in the state tree is rewritten until a human approves the proposal. ## Applying the map Only after the proposal is human-approved, apply it: - **Confirmed / unchanged capability** — write or update its considered `README.md`: what the capability is, the vision goal it cites, its boundary. Clear any `provisional` marker. This is the considered description — `capability-map`'s exclusive output. - **Reshaped capability (merge / split / rename) WITH a `changes/` history** — this is a MIGRATION, applied atomically: 1. move the affected `changes/{NNNN}-{slug}/` folders to their new capability; 2. rewrite every `why-link` and `capability:` frontmatter field in every PRD / spec / issues file that referenced the old capability; 3. write the considered README for the resulting capability(ies). A reshape that skips the migration leaves the tree with broken `why-link`s — it is not done until every link resolves again. - **A capability with shipped changes is never erased.** If the decomposition removes a capability as a standalone, its changes are folded into whichever capability absorbs them — the history moves, it is never dropped. Erasing shipped history would make the repo lie about what was built. - **Infrastructure-tier items** — record each in the capability-map output as infrastructure: below the capability layer, consumed by named capabilities, no why-link, no vision goal. Do NOT create a `capabilities/{slug}/` folder or a considered README for it — it is not a capability. When writing or updating a capability `README.md`, bump its `revision` and append a matching `## Changelog` entry in the same act — what changed and why (promotion from a provisional stub, a reshape, a reconciliation finding). Revision bump and changelog entry are atomic. After applying, every `why-link` in the tree must resolve. Verify it. `capability-map` is not the only skill that writes a capability `README.md`: `spec-breakdown` updates the present-tense README when a change ships. Any skill that writes a capability README is bound by the same atomic revision+changelog rule (see `spec-breakdown`'s "Keeping the repo true"). ## When this skill applies - Mapping a product's capabilities for the first time, or re-mapping them — this skill. - Promoting provisional capability stubs into considered capabilities — this skill. - No approved `vision.md` exists — NOT this skill; run `product-vision` first. - A single feature idea — NOT this skill; that is `change-scope` (stage 3). - Updating one capability's present-tense README because a change shipped — NOT this skill; that is `spec-breakdown`. - Discussion about product structure — not a trigger; answer normally. ## Precedence `vision.md` outranks `capability-map` — the vision is the criterion the decomposition serves; this skill never edits the vision to make a capability fit. If the decomposition exposes that the vision is incomplete, that is a finding for `product-vision` and a human, surfaced in the proposal — not something to resolve by bending the map. `capability-map` reads and writes no decision records; technical decisions are below its concern. ## What a capability README must contain A considered `capabilities/{slug}/README.md` (this skill's exclusive output): Frontmatter: ``` --- capability: {slug} revision: 1 why-link: {resolvable path + goal in product/vision.md} status: considered --- ``` Body: - **What this capability is** — the durable area of the product it covers, in present tense. - **Why it exists** — the vision goal it serves. - **Boundary** — what falls inside this capability and what belongs to a neighbouring one. - **Changelog** — per DESIGN_PRODUCT_PIPELINE.md §2b (Changelog); a newly-promoted capability's first entry is `revision 1 — — capability established`. The README is the considered description. The per-change present-tense detail of what the capability currently does is maintained by `spec-breakdown` on each ship; `capability-map` owns the considered framing, not the change-by- change present tense.