@antoneeo/agentic-sdlc-skill 1.35.0 → 1.37.0

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

@@ -1,71 +1,118 @@
 # Systematic Debugging
 
-Applies to bugs classified L2 or L3. Entered either from phase 4
-(Development and Testing) when a defect surfaces during implementation, or
-from the circuit breaker in `SKILL.md` §4 after repeated no-progress runs.
+Applies to bugs classified L2 or L3, from the start of their analysis, including
+defects discovered during implementation. Investigate the observed failure before
+proposing a definitive fix. A suspicious source-code pattern is a hypothesis, not
+proof that it caused this incident.
 
 ## Method
 
-Work the steps in order; do not skip ahead to a fix before step 3 names the
-mechanism.
-
-1. **Reproduce deterministically.** Find the smallest input or scenario that
-   triggers the bug every time. A bug you cannot reliably reproduce cannot be
-   verified as fixed.
-2. **Isolate.** Narrow the failing case to its minimal form — strip
-   unrelated setup, unrelated data, unrelated code paths. Bisect (recent
-   commits, code paths, input ranges) when the boundary is unclear.
-3. **Root cause — name the mechanism.** State in one sentence why the
-   observed behavior happens, tracing the actual execution path. Trace it by
-   enumerating the real callers/consumers of each suspect symbol with the best
-   symbol-graph tool your toolchain offers — an IDE/LSP call hierarchy or a
-   find-usages / call-graph capability — not text search; `grep`
-   under-enumerates and hides the very consumer that breaks. **MUST NOT
-   patch a symptom without naming the mechanism; why: symptom patches recur
-   and stack** — the same underlying defect resurfaces elsewhere, and each
-   unexplained patch makes the next investigation harder, not easier.
-4. **Fix at the cause**, not at the symptom identified in step 1.
-5. **Write a regression test that FAILS on the old code** (verify this
-   before applying the fix, or by temporarily reverting it) and passes after.
-   A regression test that was never confirmed to fail proves nothing.
-6. **Run the relevant suite for collateral.** A root-cause fix can change
-   behavior other callers depend on; enumerate those callers with the
-   symbol-graph (step 3), not from memory, and check them before closing.
-
-**Capture the model you had to rebuild.** If naming the mechanism (step 3) forced
-you to reconstruct the mental model of a complex component that no guide documents —
-tracing it across files because it was written down nowhere — that is the
-comprehension trigger (`guides.md` §1): it is your duty to write the `source_kind:
-code` guide, so the next debugger starts with the map you just paid to build.
-
-**Chronic fragility is a signal, not a task to grind.** If a component breaks
-*repeatedly across sessions* and its complexity is no longer under control, stop
-treating each break as an isolated bug — that pattern has two duties, not one:
-1. **Understand** — write the `source_kind: code` comprehension guide (above) so the
-   understanding stops evaporating between sessions.
-2. **Escalate the complexity itself** — STOP stacking patches on a component nobody
-   fully understands. Flag the fragility as tech debt and propose a dedicated
-   **refactor as its own L3** (Vision-gated), instead of a fourth fix. Continuing to
-   patch a component you keep breaking is the anti-pattern, not the fix.
+1. **Establish the facts.** State expected versus observed behavior, affected
+   environment, timing and last known working state. Read available local incident
+   evidence first: relevant logs, stack traces, request/response, effective
+   configuration and service state. Preserve evidence before restarts or changes
+   erase it; urgent containment may come first, but label it temporary and record
+   what evidence could not be preserved. Logs may be partial or misleading: check
+   their scope and time window. Do not exhaust every log or wait for nonexistent
+   logs when a direct observation is available. Read only what is needed, redact
+   secrets/personal data in reports, and keep sensitive raw logs out of project docs.
 
-## Circuit breaker integration
+2. **Maintain the hypotheses.** Keep a small register in the existing L2
+   mini-analysis or L3 ANALYSIS/Action Plan, not a new mandatory document:
+
+   | Cause hypothesis | Evidence for/against | Likelihood and basis | Verification cost | Check and result | Current hypothesis status |
+   |---|---|---|---|---|---|
+
+   Use high/medium/low or unknown likelihood and rough costs, with reasons; do not
+   invent numerical probabilities. Prefer hypotheses that are both more likely
+   and cheaper to verify. When those criteria conflict, choose a check with useful
+   discrimination between the remaining explanations and justify that choice.
+   State what observation would support or invalidate the hypothesis before the
+   check. Record each result, update evidence/status and reorder after every check.
+   An inconclusive check leaves the hypothesis open; distinguish a check's outcome
+   from the hypothesis's accumulated status (open, confirmed, invalidated).
+   Do not repeat an invalidated hypothesis unless new evidence reopens it.
+
+3. **Test and trace the mechanism.** Reproduce and isolate the smallest faithful
+   failing case when feasible; bisect inputs, paths or changes when informative.
+   Skip a reproduction already known to omit the incident's causal conditions;
+   choose a faithful alternative or disclose the gap. Stop diagnostic checks when
+   further results cannot change the causal or fix decision; this does not replace
+   the regression and recovery verification in step 5.
+   If the incident is intermittent or inaccessible, use captured traces and
+   targeted diagnostic observations instead of declaring investigation impossible.
+   Add minimal instrumentation when evidence is insufficient. Prefer read-only
+   checks; run state-changing experiments in a controlled environment under the
+   existing authorization boundaries. Read source to answer a concrete question
+   arising from evidence, then check its predictions against actual execution.
+   A static call graph identifies possible consumers, not the executed path.
+
+   Use the **five whys** to deepen supported causal links, not to force five
+   answers or a single linear cause. Each unsupported answer becomes a hypothesis
+   in the register. Allow interacting causes; distinguish why the failure happened
+   from why prevention or detection missed it. Stop when the actionable causal
+   mechanism is supported, or state the evidence gap instead of inventing a cause.
+   Before a definitive fix, name the mechanism and evidence connecting it to this
+   failure; explain which alternatives were invalidated and which remain open.
+   Missing logs or a passing unrelated test do not invalidate a hypothesis.
+
+4. **Correct the design with Poka-Yoke.** Fix the responsible code, configuration
+   or infrastructure; do not force a code edit for an environmental cause.
+   Enforce the invariant where the responsibility belongs: prevent the invalid
+   condition, or detect and reject it immediately with an explicit outcome when
+   prevention is infeasible. Preserve legitimate behavior; a blanket rejection or
+   crash is not universally appropriate. Prefer the smallest coherent correction
+   over a case-specific exception, duplicated guard, silent fallback or speculative
+   broad refactor. Temporary containment is not a definitive fix.
+
+   Before editing, enumerate affected consumers using the available symbol graph
+   and a text coverage probe; reconcile differences and state coverage limits.
+   With no graph available, use text/targeted reads and disclose incomplete coverage
+   rather than guessing completeness. Apply existing triage/design gates if scope
+   expands. Mandatory design verification, preserving this wording verbatim:
 
-After 3 consecutive runs without progress: STOP. Do not attempt a 4th
-variation of the same guess. Audit your assumptions from step 1 — is the
-reproduction actually deterministic, is the isolated case actually minimal,
-is the "root cause" from step 3 actually confirmed or just plausible? Then
-restart from step 1 with the corrected assumption.
+   > Dopo la correzione il software deve essere fatto come se fosse stato progettato senza quel difetto
+
+   Explain how the fix satisfies it: the correct owner enforces the invariant,
+   the same failure is prevented or detected at origin, no ad hoc exception is
+   needed, and valid consumer behavior is preserved. Disclose residual compromises;
+   the sentence does not authorize redesign beyond the confirmed defect's scope.
+
+5. **Verify the correction and collateral.** Follow `tdd.md` for implementation:
+   confirm a regression test fails for this mechanism on the old implementation
+   and passes after the fix. Verify the Poka-Yoke against invalid and valid cases,
+   relevant neighboring cases, and concurrency/retry/order where the mechanism
+   involves them. Run the relevant consumer suite after the final change.
+   If the original incident cannot be replayed, distinguish controlled mechanism
+   tests from incident recovery evidence and report remaining uncertainty; do not
+   waive available regression tests or claim an unperformed verification.
+
+**Capture the model you had to rebuild.** If tracing the cause reconstructed a
+complex component with no CURRENT comprehension guide, write its `source_kind:
+code` guide under `guides.md` §1. Keep evidence and invariants, not sensitive logs.
+
+**Chronic fragility is a signal, not a task to grind.** If the component repeatedly
+breaks across sessions and complexity is no longer controlled, preserve its model
+in that guide and surface the debt. Propose a dedicated Vision-gated L3 refactor
+instead of stacking patches; do not silently expand the current fix into it.
+
+## Circuit breaker integration
 
-If still stuck after the restart, ask the user for instructions, and hand
-over the evidence gathered so far: the minimal reproduction, what was ruled
-out, and the current best hypothesis.
+After three consecutive attempts without new diagnostic information or progress,
+STOP varying the same guess. Audit the evidence, register and checks: did a result
+actually invalidate the hypothesis, did the test reproduce the relevant conditions,
+and was the mechanism confirmed rather than merely plausible? Restart from the
+earliest unsupported step. If still stuck after that restart, ask the user for
+instructions with observed facts, checks/results, invalidated and open hypotheses,
+the evidence gap and any temporary containment. More guesses are not progress.
 
 ## Anti-patterns
 
-- **Shotgun debugging**: changing several things at once hoping one fixes it
-  — when it "works," you do not know which change mattered or why.
-- **Stacking speculative fixes**: adding a second guess on top of an
-  unverified first one instead of confirming or discarding it first.
-- **"Fixed but can't say why"**: closing the bug without a step-3 mechanism
-  statement. If you cannot name the mechanism, the fix is not confirmed —
-  it may just be masking the trigger.
+- Source-first speculation: patching a plausible defect without tying it to the incident.
+- Shotgun debugging: changing several things at once without a discriminating check.
+- Guess stacking: retaining an unverified fix while adding another.
+- Register theater: invented likelihoods, repeated cheap but uninformative checks,
+  or check failure presented as hypothesis falsification without adequate coverage.
+- Five invented whys: unsupported causal links, or forcing one root on interacting causes.
+- Symptom exceptions: suppressing one event or input instead of correcting its invariant.
+- "Fixed but can't say why": closure without causal evidence and the mandatory design check.

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

@@ -26,7 +26,11 @@ without an E-ISP.
    - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
      task block, the `produces` of prior-order tasks (interfaces), and
      `guides` pointers (paths, never pasted content) to stdout.
-   - Spawn the subagent with that brief as its entire context window.
+   - Spawn the subagent with that brief plus the return-doubts line as its
+     entire context window. The line: "An open point whose answer changes the
+     work is not yours to decide: return it in your final output with what you
+     searched." The orchestrator treats them as its own candidate doubts
+     (`elicitation.md` §When a doubt emerges).
    - Run `task.verify` out of band (the orchestrator executes it — the
      validator only ever prints it, never runs it) plus the one-shot review
      below.

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

@@ -1,30 +1,91 @@
 # Spec Elicitation
 
-`## 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
+`## The question discipline` below governs EVERY doubt and 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, or the remainder is
-derivable from the repo, `ai_docs/` and the conversation — skip the round and add
+Skip path: if the spec is already complete — an approved Vision, explicit user
+requirements or an earlier reply already answer goal, scope, and constraints, and
+any remainder is settled as §When a doubt emerges allows — 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 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.
+and a real doubt remains, do not stall and do not invent consensus. Write it as a
+**declared assumption** (§Ask before the write) in the artifact it touches. At L3,
+mark the ANALYSIS `BLOCKED on the user` and stop before implementation; below L3,
+proceed and list the assumption in the reply. 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:
+A doubt kept silent is decided by the agent alone and reaches the documents
+looking settled; a useless question wastes the user's attention. This section
+rules on both.
+
+### When a doubt emerges
+
+A **candidate doubt** is an open point whose answer changes what you build or
+write. The usual signals — they illustrate, they do not close the definition:
+
+| Thought | What it means |
+|---|---|
+| "They probably mean…", "I'll assume…" | you are choosing between readings of the request |
+| "The request doesn't say, so I'll fill it in" | a gap in scope, a non-goal, an acceptance criterion or a priority |
+| "Either would work, I'll pick one" | equivalent in effect: yours, pick and do not ask; different in effect: weigh them below |
+| "I'll note it as an assumption and move on" | with the user reachable, that note is where doubts go to be forgotten |
+| "It's reversible, it can be fixed later" | later is after the documents built on it exist |
+
+Settle it by kind:
+
+- **A fact, or information only the user holds** (a deadline, a price, a
+  constraint): settled only by evidence, cited — never settled by a weighing. Left
+  open by the search and changing the work, it is a real doubt.
+- **A choice** — a reading of intent, a design trade-off: cite the user's statement
+  that settles it (the request, an APPROVED Vision, an earlier reply); failing one,
+  weigh the pros and cons of each option, stating each rejected option
+  at its strongest — the need it serves best; a weighing won against a weak
+  version of the alternative is not a weighing. One clearly outweighs: take it and
+  write the weighing with the choice — "I take X over Z: pro …, contro …".
+  Balanced, or turning on a user priority not on record: a **real doubt** — and it
+  turns on one whenever the options serve different needs of the actor, each better
+  at one the actor would notice in using the result (reading in a spreadsheet
+  against processing by a program, a quick answer against a complete one) and
+  none good enough at both, and nothing the user wrote ranks those needs — however
+  clear your own ranking feels. "The more natural reading" with no pros and cons
+  written is not a weighing. Design is yours until it trades off something the
+  user owns. Reserved approvals never enter this test (§The form of a question).
+
+### Ask before the write
+
+A real doubt that passes the legality test below is **owed**, not merely allowed:
+the test separates a doubt from a search not yet run, it never licenses silence.
+Ask it before the first write that would embed its answer — in an analysis, plan,
+guide or code — grouped with every doubt open at that point, in one numbered set,
+with the client's structured-question facility where it has one. Never defer a
+doubt to the deliverable, where the user must find it inside the document; never
+drip one question per turn. The round below is this rule's planned occasion. Fold
+every answer into the artifact, citing the reply (§Reflect); an intent choice with
+neither a source nor a weighing is a finding (`review.md` §Reviewing).
+
+**Declared assumptions exist only where no question can be asked:**
+
+- **Unattended** — the user is not reachable (the Unattended path above).
+- **Delegated** — the user's own words handed you this choice ("your call"); quote
+  them. A general "go ahead" is not a delegation.
+
+Each states **what it is taken from** and **the alternative it excludes**, and is
+listed where the user will read it: an assumption recorded alone is a decision
+wearing an assumption's clothes, and one nobody is shown is a silent decision. A
+dispatched subagent returns its open points in its final output (`dispatch.md`);
+the orchestrator treats them as its own candidate doubts (§When a doubt emerges).
+
+### The legality test
+
+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
@@ -48,9 +109,7 @@ Never legal:
   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.
+  project's conventions. Cheapness to undo is NOT the test.
 - **Re-asking the record** — goal, scope or constraints that an APPROVED Vision,
   an earlier reply, or the request itself already states.
 
@@ -58,38 +117,20 @@ 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.)
+the system come from search.
 
 **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.
+### The form of a question
+
+The approvals reserved above and every stop the doctrine mandates are asked
+whatever you expect the answer: **legal by mandate**, never weighed, never
+re-argued here. Unattended, they are never assumed: the work holds, unless the
+mandating rule prescribes its own unattended handling (`review.md`'s gated rung
+does).
 
 **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`
@@ -103,16 +144,15 @@ 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:
+A question outside the planned occasions carries the **blocking form**, one line
+per element — surface both sides with their evidence, never silently pick one:
 
-- the fork: the concrete options and what each implies for the work;
+- the fork: the options, each with its pros and cons, 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 no assumption survives — why the weighing does not settle it, and what a
+  wrong pick costs; a reserved approval or a mandated stop cites 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.
@@ -120,14 +160,15 @@ evidence, never silently pick one:
 ## 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.
+Vision, `ai_docs/`, the conversation; the code answers facts and constraints,
+never the goal, scope or acceptance. Ask only the real doubts, and carry the
+derived answers into the round with their source or weighing ("I take X from Y;
+the questions below are what no source settles"), 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:
+exists, each with its pros and cons (this narrows the reply and speeds up the
+round). Cover:
 
 1. **Goal / benefit** — what problem this closes and why now. The answer must
    name what the actor *obtains*, not a mechanism: "a dashboard" is not an
@@ -165,6 +206,8 @@ 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.
+- **Deferring a doubt into the document**: writing a guess into the artifact
+  and leaving the user to find it there.
 - **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.