@rasensio/aidlc-content 1.32.0 → 1.34.0

package/capabilities/claude-code.yaml

@@ -3,16 +3,20 @@ questions:
   mechanism: AskUserQuestion
   directive: >-
     Render each question spec as one question in an AskUserQuestion call. The
-    interrogative sentence is the question; each option's label is its choice and
-    its consequence is the description; mark the recommendation by putting it
-    first and appending "(Recommended)" to its label. At most four options per
-    question and at least two — a spec with more must be split or narrowed. Never
-    add an explicit "Other" option: the tool supplies one, and a second is a dead
-    choice the user has to rule out. The header is a chip of at most 12
-    characters, so it names the decision, not the question. Put "Why it matters",
-    the citations and "If you say nothing" in the question file and name its path
-    in one line of the message that carries the call — they do not fit an option
-    description, and truncating them is what made questions unanswerable.
+    question text opens with the one-line what it is and its example, then the
+    interrogative sentence; each option's label is its choice and its description
+    is its observable effect on that example — who would see what, what would be
+    rejected — never the mechanism, because the description is all the user sees
+    of an option and schema terms there are what made prompts unreadable. Keep
+    mechanism terms and citations in the question file. Mark the recommendation by
+    putting it first and appending "(Recommended)" to its label. At most four
+    options per question and at least two — a spec with more must be split or
+    narrowed. Never add an explicit "Other" option: the tool supplies one, and a
+    second is a dead choice the user has to rule out. The header is a chip of at
+    most 12 characters, so it names the decision, not the question. Put "Why it
+    matters", the citations and "If you say nothing" in the question file and name
+    its path in one line of the message that carries the call — they do not fit an
+    option description, and truncating them is what made questions unanswerable.
 capabilities:
   plan-mode:
     phases: [ideation, requirements, design]

package/capabilities/codex.yaml

@@ -3,12 +3,13 @@ questions:
   mechanism: request_user_input
   directive: >-
     Render each question spec through the structured user-input request when the
-    running Codex build exposes one — the interrogative as the prompt, one entry
-    per option carrying its consequence, the recommendation named as such. When it
-    is not available, fall back to numbered prose in the message and do not
-    pretend a picker exists. Either way the question file is written first and its
-    path named in one line, because a sandboxed turn can end before an answer
-    arrives and the file is what survives it.
+    running Codex build exposes one — the one-line what it is with its example,
+    then the interrogative, as the prompt; one entry per option carrying its
+    observable effect; the recommendation named as such. When it is not available,
+    fall back to numbered prose in the message and do not pretend a picker exists.
+    Either way the question file is written first and its path named in one line,
+    because a sandboxed turn can end before an answer arrives and the file is what
+    survives it.
 capabilities:
   code-generation:
     phases: [implementation, testing]

package/capabilities/copilot.yaml

@@ -3,12 +3,13 @@ questions:
   mechanism: null
   directive: >-
     Copilot Chat has no structured question prompt, so render each spec as
-    numbered prose in the message: the interrogative as a bold line, then the
-    options as a numbered list with the consequence on each, then the
-    recommendation and the no-answer outcome. Restart option numbering at 1 for
-    every question, whatever was numbered earlier in the message — a user
-    answering "3" must be answering the third option of that question. Ask the
-    user to reply with the option number or its label.
+    numbered prose in the message: the one-line what it is with its example, then
+    the interrogative as a bold line, then the options as a numbered list with the
+    consequence on each, then the recommendation and the no-answer outcome.
+    Restart option numbering at 1 for every question, whatever was numbered
+    earlier in the message — a user answering "3" must be answering the third
+    option of that question. Ask the user to reply with the option number or its
+    label.
 capabilities:
   plan-mode:
     phases: [ideation, requirements, design]

package/capabilities/cursor.yaml

@@ -3,12 +3,13 @@ questions:
   mechanism: null
   directive: >-
     Cursor has no structured question prompt, so render each spec as numbered
-    prose in the chat: the interrogative as a bold line, then the options as a
-    numbered list with the consequence on each, then the recommendation and the
-    no-answer outcome. Restart option numbering at 1 for every question, whatever
-    was numbered earlier in the message. Name the question file by path so the
-    user can open it in the editor — Cursor puts the file a click away, which is
-    what makes the longer questions cheap to route there.
+    prose in the chat: the one-line what it is with its example, then the
+    interrogative as a bold line, then the options as a numbered list with the
+    consequence on each, then the recommendation and the no-answer outcome.
+    Restart option numbering at 1 for every question, whatever was numbered
+    earlier in the message. Name the question file by path so the user can open it
+    in the editor — Cursor puts the file a click away, which is what makes the
+    longer questions cheap to route there.
 capabilities:
   composer:
     phases: [design, implementation]

package/capabilities/kiro.yaml

@@ -3,12 +3,12 @@ questions:
   mechanism: null
   directive: >-
     Kiro has no structured question prompt, so render each spec as numbered prose
-    in the chat: the interrogative as a bold line, then the options as a numbered
-    list with the consequence on each, then the recommendation and the no-answer
-    outcome. Restart option numbering at 1 for every question, whatever was
-    numbered earlier in the message. The question file stays under `.aidlc/`, not
-    `.kiro/specs/` — a spec session is where the answer lands, not where the
-    question is recorded.
+    in the chat: the one-line what it is with its example, then the interrogative
+    as a bold line, then the options as a numbered list with the consequence on
+    each, then the recommendation and the no-answer outcome. Restart option
+    numbering at 1 for every question, whatever was numbered earlier in the
+    message. The question file stays under `.aidlc/`, not `.kiro/specs/` — a spec
+    session is where the answer lands, not where the question is recorded.
 capabilities:
   spec-driven-development:
     phases: [requirements, design, implementation]

package/capabilities/windsurf.yaml

@@ -3,13 +3,14 @@ questions:
   mechanism: null
   directive: >-
     Windsurf has no structured question prompt, so render each spec as numbered
-    prose in Cascade: the interrogative as a bold line, then the options as a
-    numbered list with the consequence on each, then the recommendation and the
-    no-answer outcome. Restart option numbering at 1 for every question, whatever
-    was numbered earlier in the message. Windsurf's context window is the tightest
-    of the supported platforms, so route to the question file sooner here — keep
-    the rendered prompt to the interrogative, the option labels and the file path,
-    and leave the citations in the file.
+    prose in Cascade: the one-line what it is with its example, then the
+    interrogative as a bold line, then the options as a numbered list with the
+    consequence on each, then the recommendation and the no-answer outcome.
+    Restart option numbering at 1 for every question, whatever was numbered
+    earlier in the message. Windsurf's context window is the tightest of the
+    supported platforms, so route to the question file sooner here — keep the
+    rendered prompt to the what-it-is line, the interrogative, the option labels
+    and the file path, and leave the citations in the file.
 capabilities:
   cascade:
     phases: [implementation]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/00-overview.md

@@ -165,12 +165,17 @@ Ask the user something when **different answers would change an artifact, a desi
 Every question is written first as a **spec** — platform-neutral, and never printed into the conversation. It carries, at minimum:
 
 - **The decision**, as one interrogative sentence.
+- **What it is** — what the thing being decided is and what it does, in plain words, shown on one concrete example with names, values or dates. Required on every question: the person answering owns the decision but was not in your research, and does not carry the vocabulary you just read. For an everyday concept this is one sentence; its length scales, its presence does not.
 - **Why it matters** — what it blocks, and what goes wrong if it is guessed.
-- **What the repo already says** — cited as `path:line`, or `path` when the whole file is the point. "Nothing found" is a valid citation; saying nothing is not.
-- **Two to four options**, each with its consequence spelled out.
+- **What the repo already says** — cited as `path:line`, or `path` when the whole file is the point. "Nothing found" is a valid citation; saying nothing is not. Schema terms, mechanism names and citations belong here, not in the options.
+- **Two to four options**, each defined by its observable effect — who sees what, what gets rejected, what gets flagged — with its consequence spelled out. Say what would happen, not how it would be built.
 - **A recommendation**, marked as such — exactly one, with the reason it wins.
 - **If you say nothing** — the outcome of no answer, so that not answering is a choice rather than a stall.
 
+When several questions in one file share a concept, open the file with one shared primer that explains it, and have every question reuse the same running example rather than inventing a new one. The reader learns the example once and then sees each option applied to it.
+
+The example shows what would really happen. One simplified until it changes the answer misleads as badly as jargon does, and it is harder to spot.
+
 Expand every identifier on first use, writing the thing out with the tag in parentheses — "the citation rule (AC-1)", not a bare `AC-1`, `FR3` or `unit-4`. A bare tag assumes the reader carries a mapping they do not have.
 
 ### Rendering the spec
@@ -197,6 +202,11 @@ With no interactive terminal, write the file, say where it is, and end the turn.
 
 When the user shares an idea tangential to the current work, offer to record it in `.aidlc/roadmap/inbox/` (see **aidlc-roadmap**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.
 
+Safe for the instance is not the same as free for the person, so two rules bind every item an instance writes, exactly as they bind the capture flow:
+
+- **Merge first.** If an open item already owns the area, append a dated `## Received from <instance>` section to that item instead of writing a new one.
+- **No item enters `inbox/` without its six-line executive summary** (the labels are in **aidlc-roadmap**). Write it from what you know; `Not yet decided.` is a valid value for any label, an absent section is not. An item nobody can triage from the top of the file is not a captured idea, it is a decision deferred onto somebody else.
+
 ## Amendments — changing a completed phase's artifact
 
 A completed phase's artifact is changed **only through an amendment**, never edited in

package/skills/04-roadmap.md

@@ -35,7 +35,15 @@ Projects have more than one person proposing work, with mixed technical depth, s
 
 **The directory an item sits in is its status.** There is no `status` field, and you must never add one — two representations of one fact drift apart, and a wrong status is indistinguishable from a right one. Changing status means moving the file.
 
-`hold/` holds both parked and declined items. That conflation is deliberate; `history` and the git log distinguish them when anyone asks.
+`hold/` holds both parked and declined items, and **the history entry says which**. One directory is deliberate — a sixth status would have to be threaded through every count, every move and every projection — but "not now" and "not ever" are different decisions, and until the reason was written down they were indistinguishable on disk. So every move into `hold/` carries a reason, prefixed `parked — ` or `declined — `:
+
+```yaml
+history:
+  - { status: backlog, at: 2026-09-22 }
+  - { status: hold, at: 2026-09-23, reason: "parked — gated on the accounts table" }
+```
+
+The consequence worth stating: **agreed work waiting on a trigger belongs in `hold/`, parked, not in `backlog/`.** `backlog/` means "could start now", and an item gated on something that does not exist yet sitting there makes every count of what is ready wrong. Parking it is not dropping it, and the reason is what proves that.
 
 ## Item Format
 
@@ -59,7 +67,7 @@ history:
 - **`id`** is assigned once and never recomputed. Renaming the file or moving it between statuses leaves it unchanged. The `item-` prefix keeps it textually distinct from the filename so nothing derives one from the other.
 - **`source`** records how the item was written: `human` directly, `agent` drafted by an AI agent from someone's description, `import` migrated from an older format.
 - **`depends_on`** names other items by `id`, so a dependency survives its target moving. Build order is derived from this graph when needed — there is no global `order` field, because concurrent capture from independent sessions cannot coordinate a sequence.
-- **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry.
+- **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry. An entry may carry a third key, `reason`, and a move into `hold/` must; always write it **inside double quotes**, because the entry is a flow mapping and a reason containing a comma or a colon ends it early and takes the whole item's frontmatter with it.
 
 Bodies are otherwise free-form. Items authored through the portable skill carry four further headings — Problem, Who it's for, What success looks like, Out of scope — which is a useful shape, not a validated one.
 
@@ -104,6 +112,8 @@ The first section of the body, before anything else, is `## Executive Summary`
 
 This exists so a triage decision can be made from the top of the file. An item whose value cannot be stated in six lines is an item nobody can decide about, and it will sit in `inbox/` until somebody re-derives the case from scratch.
 
+**The rule binds every path that writes into `inbox/`, not just this skill's capture flow.** That includes an item written by an instance mid-phase, one drafted from a conversation that never touched capture, and one you write by hand. It was already the rule here and it was already followed here; what went wrong is that the other paths were never told. On 2026-09-23, 13 of the 18 items in one project's inbox had no summary — every one of them written by an instance, none of them triageable without re-deriving the case first. `Not yet decided.` is a valid value for any label; an absent section is not a valid item. `aidlc doctor` reports `inbox/` items missing one, by name and by missing label; it never writes one, because an invented case reads exactly like a real one.
+
 Four rules keep it honest:
 
 - **`None` is a real answer for revenue, and often the correct one.** Lifecycle plumbing earns nothing directly. Writing `Indirect` for everything makes the field useless, which is worse than leaving it blank because it reads as answered. This is also the cheapest available check against the self-repair trap: a meta-feature that has to write `Revenue — None` and `Customer value — none, it observes the lifecycle` has declared itself.
@@ -118,9 +128,10 @@ Older items may predate this section. Add it when you next touch such an item
 1. **Resolve the roadmap root.** Always write to the **primary checkout's** `.aidlc/roadmap/`, never a worktree's copy: resolve via `git rev-parse --git-common-dir` (the directory containing that path is the primary checkout). Outside a git repo, use the current project root. Create `inbox/` if missing.
 2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug.
 3. **Handle collisions.** If the filename already exists in *any* status directory, ask one question — extend the existing item or new item? On extend, append a dated `## Update (YYYY-MM-DD)` section to it where it is; on new, suffix the slug (`-2`). Never silently overwrite.
-4. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
-5. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
-6. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
+4. **Merge first.** Before writing a new file, check whether an open item — anything in `inbox/`, `backlog/` or `in-progress/` — already owns the area this is about. If one does, append a dated `## Received from <source>` section to **that** item and stop; say which item it went to. This is about *subject*, where step 3 is about *filename*: four of those eighteen items were findings about areas an existing item already owned, one of them literally asking somebody to triage another item. Merging them took minutes and removed four files. A new file is the right answer when no open item owns the area — which is most of the time, and the check costs one read of a list you are already looking at.
+5. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
+6. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
+7. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
 
 **Hard rule:** capture never reads or writes anything under `.aidlc/state/` — no claims, no phase files, no transitions log. Two sessions capturing simultaneously just produce two files; no locking exists or is needed. Do not auto-commit; staging is the user's.
 
@@ -130,13 +141,17 @@ If the user includes credentials, tokens, or secrets in a braindump, flag it and
 
 List each status directory, reading **only frontmatter and the containing directory** — never item bodies. Show each item's date, title, status, and dependencies. Group by status in lifecycle order and give a count per status. Flag `inbox/` items first: they are waiting on a decision only a human can make. Then flag `backlog/` items whose dependencies are all `done` — those are the natural next candidates. Offer to open, triage, promote, or drop.
 
+For a `hold/` item, show whether it is **parked or declined**, with its reason, from the last `history` entry — that entry is in the frontmatter, so this costs nothing extra. An item with no reason recorded is reported as `hold — reason not recorded`, never guessed at: parked and declined are opposite answers, and a wrong one either revives work somebody killed or buries work somebody agreed to.
+
 The frontmatter-only rule holds for browsing, which is a list and must stay cheap enough to run over the whole roadmap. **Triage** below is the one flow allowed into the body, and only as far as the executive summary.
 
 A filename appearing in two status directories is an error: report it rather than guessing which one is current.
 
 ## Triage
 
-Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now". Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
+Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now", and carries a reason prefixed `parked — ` or `declined — `. Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
+
+Work you agree with but cannot start — gated on a trigger, a decision, or something that does not exist yet — goes to `hold/` as `parked`, not to `backlog/`. Parking it with its trigger written down is the whole difference between a backlog you can read as "ready" and one where two of eleven entries are waiting on something.
 
 Triage is the one flow that reads into the body, and it reads **the executive summary and nothing else**. Six labelled lines per item is what makes triaging a full inbox in one sitting possible; opening whole items is what makes triage something nobody ever gets round to. Show the summary, say which way you would go and why, and let the human decide. If an item has no executive summary, write one from what the item says before asking for a decision — a decision made without one is a decision made twice.
 
@@ -159,7 +174,7 @@ When the instance completes, the `roadmap-done` lifecycle action moves the item
 
 ## Drop
 
-Move the item to `hold/` and append the `history` entry. Dropping is an explicit act — never delete or overwrite an item to get rid of it.
+Move the item to `hold/` and append the `history` entry, with a reason prefixed `declined — `. Dropping is an explicit act — never delete or overwrite an item to get rid of it, and never leave the reason off: `hold/` holds parked work too, and an unexplained entry there is a decision nobody can tell apart from the opposite one.
 
 ## Projecting to GitHub Issues
 

package/skills/05-constitution.md

@@ -145,6 +145,12 @@ Vision source: <path> (<n> statements added, <m> removed)
 
 ## Should NOT-2 still stand, now that the statement it cites is gone?
 
+**What it is:** NOT-2 is one of this repo's "must never" rules, and each one
+points at the vision sentence it came from. Say NOT-2 reads "never store
+customer card numbers" and points at the vision line "we do not handle
+payments". That line has now been deleted from the vision, so the rule points
+at nothing.
+
 **Why it matters:** NOT-2 is a boundary this repo is held to. Left citing a
 statement the vision no longer carries, it is enforced without a source.
 

package/skills/90-retrospective.md

@@ -30,9 +30,11 @@ Run the retro **before** any completion cleanup (worktree removal, claim release
 3. **Ask — one round-trip.** Three questions in a single message: what surprised us? what would we do differently? what took longer than expected? For **Micro scope**, compress to one question: "anything surprising, worth doing differently, or slower than expected?" Declining the retro is fine: remove the marker, write nothing.
 4. **Write `retrospective.md`** in the instance state dir: the answers; instance metadata (template, scope); per-phase durations (pair each transitions.log `to: X` with the next `from: X`; fall back to the phase YAML's `entered_at`/`completed_at`; note inconsistencies rather than guessing); and the cost summary when available.
 5. **Distill lessons — 0 to 3.** A lesson is a durable, project-general observation ("NDJSON merge=union false-dedups identical same-second events"), not an instance anecdote ("we finished late"). If nothing generalizes, write no lesson — an empty distillation is a valid outcome.
-6. **Confirm, then append.** Show the distilled entry verbatim and get one confirmation for the whole entry. Never append unconfirmed text — lessons are auto-loaded into every future session, so this confirmation is the injection gate. Redact anything resembling credentials or secrets. On confirm, append to the lessons layer per the write rules below.
-7. **Commit** `retrospective.md` and the lessons append to the **current branch** now, before any worktree cleanup runs.
-8. **Remove the retro-pending marker** if one exists.
+6. **Cap the follow-ups — 0 to 2 queued roadmap items.** Rank what the work turned up and queue at most the top two into `.aidlc/roadmap/inbox/`, each with its six-line executive summary (see **aidlc-roadmap**). **Zero is a valid outcome**, and often the right one. This is the same cap, in the same shape, as the 0–3 on lessons, and it exists because the lessons cap alone was half a brake: the framework capped what an instance *learned* and capped nothing about what it *queued*, so closing an instance reliably grew the backlog. One measured project emitted five to nine items per close; triage kept three of eighteen.
+7. **Record the rest as observed, not queued.** Everything past the cap goes into `retrospective.md` under `## Observed, not queued`, one line each. **The cap is on queued items, not on observations** — a retro that noticed nine things writes nine and queues two. Findable, attributable, and costing nobody a triage decision. If one of them matters later, it is already written down; promote it then, with the same summary rule.
+8. **Confirm, then append.** Show the distilled entry verbatim and get one confirmation for the whole entry. Never append unconfirmed text — lessons are auto-loaded into every future session, so this confirmation is the injection gate. Redact anything resembling credentials or secrets. On confirm, append to the lessons layer per the write rules below.
+9. **Commit** `retrospective.md` and the lessons append to the **current branch** now, before any worktree cleanup runs.
+10. **Remove the retro-pending marker** if one exists.
 
 ## Lessons Layer — Write Rules
 
@@ -85,5 +87,6 @@ Run only in the **primary checkout** (not a linked worktree — check `git rev-p
 ## Rules
 
 - The retro never blocks completion: it is non-blocking, declinable, and its absence is never an error.
+- The follow-up cap is never a reason to *not notice* something. Merge first — if an open roadmap item already owns the area, append a dated `## Received from <instance>` section to it rather than spending one of the two slots on a file that duplicates it.
 - Never write lessons without the step-6 confirmation. Never record credentials or secrets.
 - Lessons are historical observations, not directives — phrase them as what was learned, not as instructions to obey.