@antoneeo/agentic-sdlc-skill 1.19.0 → 1.20.3

package/skills/agentic-sdlc-skill/elicitation.md

@@ -1,22 +1,130 @@
 # Spec Elicitation
 
-Applies when an L3 request enters phase 3 (Request Analysis), BEFORE
-drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP (Hybrid).
+`## The question discipline` below governs EVERY question to the user — any
+phase, any level, inside or outside the round. The rest of the file is the spec
+elicitation round: it applies when an L3 request enters phase 3 (Request
+Analysis), BEFORE drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP
+(Hybrid).
 
-Skip path: if the spec is already complete — an approved Vision or explicit
-user requirements already answer goal, scope, and constraints — skip the
-round and add a one-line note in the analysis stating why it was skipped.
-Do not run the round as a formality when the answers are already on record.
+Skip path: if the spec is already complete — an approved Vision or explicit user
+requirements already answer goal, scope, and constraints, or the remainder is
+derivable from the repo, `ai_docs/` and the conversation — skip the round and add
+a one-line note in the analysis stating why it was skipped and naming the
+sources. Do not run the round as a formality when the answers are already on
+record.
 
-Unattended path: when the user is not reachable (a scheduled or autonomous run,
-and a bootstrap Vision is `DRAFT` by mandate, so the skip path above cannot
-apply on a project's first L3), do not stall and do not invent consensus. Write
-the six answers as **declared assumptions** in `## Objective`, mark the ANALYSIS
-`BLOCKED on the user`, and stop before implementation. An assumption on the
-record is reviewable; a guess folded silently into a design is not.
+Unattended path: when the user is not reachable (a scheduled or autonomous run)
+and the skip path does not answer all six, do not stall and do not invent
+consensus. Write the missing answers as **declared assumptions** in
+`## Objective`, mark the ANALYSIS `BLOCKED on the user`, and stop before
+implementation. An assumption on the record is reviewable; a guess folded
+silently into a design is not.
+
+## The question discipline
+
+A question to the user spends their attention and stalls the work; the round
+below is the only place the process *plans* that cost. Everywhere, a question is
+legal only when BOTH hold:
+
+1. **Searched first, and the search is named — with its result.** The answer is
+   not on record and not derivable from the repo, `ai_docs/`, the Vision or the
+   conversation — and the question states the terms, tools and areas you searched
+   **and what they returned**. Same standard as a router verdict or an
+   architect-pass MISSING, and it carries their floors, not only their vocabulary
+   (`architect.md`, `guides.md`): a search whose scope does not cover the question
+   is not a search; a hit you did not open does not narrow anything; and **never
+   fake the search** — "I looked and found nothing" that names no terms and no
+   areas is a search not run. A question the repo can answer is a search
+   outsourced to the user.
+2. **It names what is blocked.** The question states the specific decision or
+   fact that cannot be resolved without the reply — what you will do differently
+   depending on the answer. If nothing downstream changes with the answer, there
+   is no question.
+
+Never legal:
+
+- **Generic confirmation** — "shall I proceed?", "is this OK?". The process
+  authorizes proceeding; if a real risk motivates the ask, name the risk and the
+  fork — that is a blocking question and carries the form below.
+- **Preference-fishing** — asking the user to pick among options that are
+  equivalent **in their effect on the benefit** and already decided by the
+  project's conventions. Cheapness to undo is NOT the test: nearly everything is
+  reversible under version control, and "it is reversible" as a licence to stop
+  asking is the silence-side evasion this clause must not fund.
+- **Re-asking the record** — goal, scope or constraints that an APPROVED Vision,
+  an earlier reply, or the request itself already states.
+
+What questions are FOR — what the user uniquely owns: the benefit, priorities
+between conflicting goods, non-goals, acceptance, and the approvals doctrine
+reserves to them (Vision promotion and amendment, scope changes, proposal
+acceptance, merge decisions). Facts about intent come from the user; facts about
+the system come from search. (The marketing sibling states the same rule as "ask
+only what the user uniquely owns"; this is its code-domain form.)
+
+**Precedence, because both halves can fire at once:** this paragraph wins over
+the "never legal" list above it. A choice the user uniquely owns is never
+preference-fishing, however cheap it is to undo; the list reaches choices that
+are *not* theirs.
+
+**Default non-blocking.** An unknown on which no fork of the work depends: write
+it as a **declared assumption** in the artifact it touches — the same mechanism
+the unattended path uses — proceed, and present the open points **batched**, with
+the round for spec questions or with the deliverable otherwise, answered by
+exception.
+
+This is the path most work takes, so it carries the SAME evidence duty as a
+question, not a lighter one — otherwise "assume it" becomes the way to skip the
+standard. Each declared assumption states **what it is taken from** ("I take X
+from Y" — the same shape the round uses) and **the alternative it excludes**, and
+**every declared assumption reaches the batch**: an assumption nobody is shown is
+not an open point, it is a silent decision. That pairing is what the kb family's
+escalation rule actually does — keep BOTH sides with their sources and surface
+them, never silently pick one — and this branch, not the blocking one, is where
+it structurally belongs. An assumption recorded with its source and its rejected
+alternative is reviewable; one recorded alone is a decision wearing an
+assumption's clothes, and a session stalled on a question that could have been
+an assumption is the waste this section exists to prevent.
+
+**Blocking is reserved** for three cases: proceeding under ANY assumption would
+waste the work (the forks diverge at once, and the wrong branch is rework of the
+whole unit); the doctrine reserves the decision to the user (the approvals
+above); or the doctrine itself mandates the stop — and a mandated stop is legal
+by mandate, never re-argued here.
+
+**Exactly two mandating files prescribe their own hand-over, and there the form
+below does not apply** (two forms over one moment is the duplicate `review.md`
+§Reviewing forbids): `debugging.md`'s circuit breaker — the minimal reproduction,
+what was ruled out, the current best hypothesis; and `review.md`'s round cap —
+the artifact plus the open findings. That list is closed. **Every other mandated
+stop carries the form**, including one that names only its options and not its
+evidence (`SKILL.md`'s Vision-Gate conflict names the two choices — the evidence
+is still owed, and for a Vision conflict the quoted line IS the substance) and
+one that prescribes nothing (`guides.md`'s guide proposal and its ingestion
+bound). "The file mentions the moment" is not a prescription; only a stated
+hand-over is.
+
+A blocking question carries a mandatory form — surface both sides with their
+evidence, never silently pick one:
+
+- the fork: the concrete options and what each implies for the work;
+- the evidence: what you searched, read or tried, and what it leaves undecided;
+- why no assumption survives — what work is discarded if you assume and are
+  wrong. This is what makes case (a) falsifiable: without it, "this is a fork"
+  is an agent's assertion about its own convenience, and case (a) becomes the
+  licence for exactly the question this section forbids. Cases (b) and (c) answer
+  it by citing the approval or the mandate instead;
+- why it is the user's call — what makes the remainder intent, priority or
+  approval rather than a derivable fact;
+- what stays blocked until answered.
 
 ## The round
 
+**Derive before asking.** Answer each of the six from the record first — the
+Vision, `ai_docs/`, the conversation, the code. Ask only the residue, and carry
+the derived answers into the round as declared assumptions corrected by
+exception ("I take X from Y; the questions below are what no source answers"),
+not re-confirmed one by one.
+
 Ask ONE structured set of questions, not a drip of follow-ups. Keep each
 question short and numbered; offer concrete options where a real choice
 exists (this narrows the reply and speeds up the round). Cover:
@@ -53,8 +161,9 @@ run a second round to double-check answers that were already clear.
 
 - **Interrogation**: an endless list of questions, or drip-feeding one
   question at a time across many turns instead of one structured round.
-- **Asking what the approved vision already answers**: re-asking goal or
-  non-goals that a `Status: APPROVED` Vision or M-VISION already states.
 - **Collecting answers without folding them in**: getting replies in chat
   and proceeding to design without writing them into the analysis document —
   the next reader has no record of why the scope is what it is.
+
+(The illegal question forms — generic confirmation, preference-fishing,
+re-asking the record — are defined once, in `## The question discipline`.)

package/skills/agentic-sdlc-skill/review.md

@@ -85,6 +85,14 @@ When you hand work to a reviewer (human or agent), give them:
   should have been. The design reviewer checks that every threat surface the change
   touches has a matching security requirement.
 
+**The verdict travels back as the reviewer's own final output** — the text it
+returns when it finishes, nothing else. A reviewer that tries to message the
+requester mid-run depends on a delivery channel it cannot verify (a subagent
+addressed by agent TYPE rather than by session gets no such channel, and the
+attempt fails silently); a requester that waits for such a message stalls
+holding a verdict that already exists. State the return form when you request
+the review, and read the verdict where it actually arrives.
+
 Never ask a reviewer to "review my session" or "review what I just did"
 without the artifacts above — that forces them to reconstruct scope from
 conversation instead of reviewing the change itself. Say which finding
@@ -109,6 +117,10 @@ When you are the reviewer:
 
 - Verify claims against the real source, not against the diff's own
   description of itself.
+- **Your verdict is your final output.** Deliver findings and verdict as the text
+  you return when you finish — never only through a message to the requester, a
+  channel you cannot verify and which fails silently when it is not there
+  (see `## Requesting`).
 - Cite evidence as `file:line` for every finding — a finding without a
   location is not actionable.
 - Keep severity honest: do not inflate a style preference to a blocker, and
@@ -125,20 +137,30 @@ When you are the reviewer:
   statement is the proof the check ran; an unfalsifiable "I checked" is the review
   theater this discipline exists to prevent (the reviewer-side twin of §Receiving's
   silent-drop rule). Plain code reviews stay findings-only.
+- **Restated facts (cite, never copy).** Every governance slot has ONE owning document
+  per project. A fact restated in the artifact under review when another document owns
+  it is a **finding**: the fix is a citation naming the owner, not a better copy. This
+  binds the conformance statement too — where a constraint is satisfied by another
+  document, name that document as the evidence instead of repeating what it says. Two
+  copies of one fact diverge at the first edit, and the reader then has no way to tell
+  which one is current. The rule bites hardest across domains, where the same slot
+  ("threat model", "vision", "handoff") carries a different meaning under each lens and
+  a copy looks like an independent second source.
 - **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
-  that carries NO Capability Ledger is itself a finding** — the architect pass left
+  that carries NO Capability Ledger is itself a finding** — the lens's capability
+  pass (`architect.md` in the code lens, `taxonomy.md` in the knowledge lens) left
   no record, and "the artifact does not have one" is what a skipped pass looks like,
   not a reason to skip the check. (This half is load-bearing in Hybrid, where the
   validator backstop reads Standalone ANALYSIS files only and this clause is the
   sole check that the pass ran.) When the ledger is there, map each
   ledger row to where the design or diff realizes it. Three findings live here and
-  nowhere else (`architect.md`): a capability ruled MISSING but implemented inside
+  nowhere else (the capability-pass file named above): a capability ruled MISSING but implemented inside
   the feature's code path, with no component owning it; a component whose contract
   names the feature (a second consumer would force it open); and a capability ruled
   MISSING, not built, and absorbed by quietly reshaping the feature — that is a
   scope change owed to the user, not a design detail. An EXISTS row with no named
   path or symbol is itself a finding. A capability built in this change and absent
-  from the `## Component Map` (`strategic/architecture.md`) is a finding too — and
+  from the `## Component Map` (`strategic/architecture.md`, where the lens keeps one) is a finding too — and
   so is **a component the pass merely DISCOVERED and did not write**, especially
   when the change marks that area ANALYZED: the area now looks read, the map is
   still silent, and the next feature may lawfully rule the capability MISSING and

package/skills/agentic-sdlc-skill/routing.md

@@ -0,0 +1,100 @@
+# Domain Routing — which lens owns this unit of work
+
+The family ships as sibling skills built from one shared core: each lens carries its
+own **fidelity discipline** (what the work must be faithful to) and its own validation
+rules, over **one** `ai_docs/` tree. This file answers one question: *which lens's
+method governs THIS unit of work?* It does not decide where the resulting file is
+stored (step 5), and it never runs before the triage level is known — L1 never
+reaches it.
+
+## 0. Installed-lens detection — run first, fail open
+
+Look in the skills directory this skill was loaded from for sibling lenses of the
+family, identified by the `name:` in their `SKILL.md`:
+
+| Lens | Skill name | Faithful to |
+|---|---|---|
+| code | `agentic-sdlc` | this repository's code |
+| knowledge | `kb-agentic` | documents the user supplied |
+| marketing | `mkt-agentic-sdlc` | market evidence |
+
+- **No sibling installed, or the directory cannot be read** → the router does NOT run.
+  Work under the loaded lens; read no further. This is the normal single-lens case and
+  it costs nothing.
+- **At least one sibling installed** → run the router below, after the level test, on
+  every L2, L3 and Spike.
+
+Fail-open is deliberate: a detection that cannot answer must never block the work. A
+single-lens project that silently gains a router verdict it cannot act on is worse
+than no verdict at all.
+
+## 1. The router
+
+Run the steps in order. Stop at the first one that decides.
+
+1. **Fidelity / purpose.** What must the work be faithful to?
+   - *This repository's code* → provisional **code**; continue to step 2.
+   - *Documents the user supplied* → **knowledge**. Decided.
+   - *Market evidence* → **marketing**. Decided.
+   - *A deliverable whose purpose is market-facing persuasion* (copy, positioning,
+     campaign material) → **marketing regardless of source**. Decided. Without this
+     branch the marketing lens is reachable only when the *source* is market evidence,
+     never when the *purpose* is marketing — and the launch post written from the
+     release notes routes to code.
+
+2. **Deliverable class** — only on the provisional `code` branch. The predicate is on
+   the deliverable, not on its audience:
+   - *Part of this repository's own document set, shipping and maintained with the
+     code* (`ai_docs/`, README, CHANGELOG, comprehension guides, migration notes) →
+     **code**; continue to step 3.
+   - *A standalone knowledge deliverable whose fidelity extends beyond this repo's
+     code* (user documentation for an external audience, a distilled corpus) →
+     **knowledge**. Decided; step 3 is not reached.
+
+3. **Build-consumed override** — only on the provisional `code` branch, never
+   overriding a *marketing* or *supplied-documents* verdict. *Is the deliverable a
+   file the project's build or test toolchain consumes?* Executable or imported
+   source: yes. Committed Markdown: no. A yes confirms **code**.
+
+4. **Split rule.** A request whose work must be faithful to two sources is **two units
+   of work**, split before routing: the distillation (knowledge) and the design that
+   cites it (code) each route alone. The router returns one lens per unit; it never
+   returns two lenses for one unit.
+
+5. **Owning tree.** A straddling artifact keeps its lens for *method* and takes this
+   repository's tree and validator for *storage*. Lens and location are separate
+   answers — a marketing-lens document written in a code repository still lives in
+   that repository's `ai_docs/` and passes that project's validator.
+
+6. **Cross-check.** If the verdict contradicts an installed skill's `description`, the
+   descriptions are wrong: fix them. Never silently override the test with a
+   description.
+
+## 2. Worked verdicts
+
+| Request | 1 | 2 | 3 | Lens |
+|---|---|---|---|---|
+| "write the API reference docs" (hand-written, ships with the repo) | code | repo's own doc set → code | not build-consumed → no flip | **code** |
+| "write user documentation for our customers' admins" | code | standalone knowledge deliverable → knowledge | n/a (left the code branch at 2) | **knowledge** |
+| "write the API reference docs" (generated — the work edits docstrings in source) | code | repo's own doc set → code | **build-consumed: yes → confirms code** | **code** |
+| "write a comprehension guide for the auth module" | code | repo's own doc set → code | not build-consumed → no flip | **code** |
+| "turn these vendor specs into a technical design" | split (step 4): spec = supplied docs; design = this repo | — | — | **knowledge** for the distillation; **code** for the design, citing it |
+| "write the pricing page copy from our market research" | **purpose: market-facing → marketing** | never reached | never reached | **marketing**; stored in this repo's tree (step 5) |
+| "write the launch blog post from the release notes" | purpose: market-facing → marketing | never reached | never reached | **marketing** |
+
+## 3. Acting on the verdict
+
+The verdict binds the **method and the validation rules**, not the storage:
+
+- **Verdict = the loaded lens** → continue; nothing changes.
+- **Verdict = a sibling lens** → say so, and work that unit under the sibling's method
+  and its rule set (its templates, its mandatory risk section — code
+  `## Security and Threat Model`, knowledge `## Sources and Verification`, marketing
+  `## Threat Map / Plan Risks`). The artifact is written with an explicit
+  `domain:` field so the answer survives the session, and it stays in this project's
+  `ai_docs/` tree (step 5).
+- **The unit was split** (step 4) → route and declare each half separately.
+
+Documents under `vision/` — the project vision, principles, the roadmap — sit **above**
+the domain split: they belong to no lens and are validated by the core's structural
+rules only. The router is not consulted for them.