@rasensio/aidlc-content 1.33.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.33.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

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.