@antoneeo/agentic-sdlc-skill 1.36.0 → 1.37.0

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

@@ -1,215 +1,215 @@
-# The Architect Pass
-
-Applies at L3, in phase 3, AFTER the spec elicitation and BEFORE the Impact is
-drafted. It answers the one question the Impact cannot ask: *does the system
-already have the components and services this feature needs?*
-
-Why it exists: **a feature is not a unit of construction.** Left alone, an agent
-designs the feature and builds whatever it lacks inside the feature's own code
-path — so no component owns the capability, the next feature that needs it
-rebuilds it differently, and the platform accretes feature-shaped code nobody can
-reuse. That is myopia one level above the file: the change is complete, the tests
-pass, and the architecture is worse.
-
-## 1. State the feature as capabilities, not as files
-
-Write what the system must be able to DO for this feature to exist — "persist a
-draft across sessions", "notify a third party asynchronously", "authorize per
-tenant". A capability is a verb over a domain noun. It names no file, no class and
-no library: **that** is the decoupling. Files come later, in the Impact.
-
-Two or three capabilities is a normal feature. When the list has one obvious entry
-and it plainly exists, say so in one line **under the `## Capability Ledger`
-heading, still naming the component and where it lives**, and move on — this pass
-is a question to answer, not a form to fill. The heading is what makes a cheap
-answer distinguishable from a skipped pass; a bare "everything already exists"
-names nothing and is the **Paper ledger** anti-pattern, not the licence.
-
-## 2. Rule each capability against the platform
-
-One verdict per capability:
-
-| Verdict | Meaning | What the row must carry |
-|---|---|---|
-| **EXISTS** | a component already owns this capability and covers the need | the component, where it lives (path / symbol), and the one guarantee you re-read it to confirm |
-| **INADEQUATE** | a component owns it but does not cover the need | the same, plus the gap in one line |
-| **MISSING** | no component owns it | the terms you searched, the tool, and the areas covered |
-
-Read the **`## Component Map`** in `strategic/architecture.md` first — the project's
-inventory of what owns which capability, kept so this pass does not re-derive the
-platform from source every session.
-
-**The map is a cache of evidence somebody already paid for. It lowers the COST of a
-verdict, never the STANDARD of one.** Every verdict carries the same evidence
-whether the map answered it or not; a hit means the search is already written down,
-a miss means you pay full price. Reading a row does not excuse you from checking
-that it is still true — the map is the index, the code is the evidence.
-
-**Its silence is unread, not empty.** The map covers only the areas `audit/
-audit_plan.md` marks ANALYZED — and that state is a claim someone made, not a fact
-the tooling verified: marking asserts *the area was read closely enough to name the
-capabilities it owns*, so an area marked after two greps is a false ANALYZED and
-the person who wrote it owns the duplicate that follows. In an area still PENDING —
-or SKIPPED, or absent from the plan entirely — **the map can never ground a MISSING
-verdict.** Nothing there has been looked at yet, and "the inventory does not mention
-it" is the reasoning that builds a second copy of a component that already exists.
-
-**Searching for an owner** is text search first, symbol-graph second — in that
-order, because you are looking for a name you do not know yet, and a call-hierarchy
-tool needs a resolved symbol as *input*. Grep the repository (minus SKIPPED areas)
-for the domain noun, at least two plausible synonyms, and the verb; then use the
-symbol-graph tool to confirm or dismiss the candidates the search surfaced.
-
-**The floor for a MISSING** is about triage, not term count: every hit that lands in
-an unmapped area gets opened, or the MISSING is **provisional** and says so in its
-row. Record what you ran — terms, tool, areas — and stop when the terms are
-exhausted and no candidate remains unopened. A provisional MISSING is honest and
-cheap; an unfalsifiable one is the same defect as an EXISTS with no symbol named.
-
-**Understanding is never deferred; only WRITING the map is.** You may leave the rest
-of the repository unmapped and grow the inventory feature by feature — you may not
-leave unexamined anything this change touches or depends on. That blast zone is
-understood now, at full standard, mapped or not. The incremental licence is about
-the artifact, never about the comprehension.
-
-Ground every verdict. An EXISTS with no named symbol is an assumption wearing a
-verdict's clothes, and it is the row that breaks in implementation. A MISSING
-declared without a real search is how duplication enters — the component may be
-there under a name you did not guess. This is the DRY check at architecture level.
-
-## 3. Design what is missing as a component, not as feature internals
-
-INADEQUATE and MISSING produce design work of their own, governed by one rule:
-
-**The component's contract is stated in the component's own vocabulary. The feature
-is one consumer, never the owner.**
-
-The test is mechanical: write the contract — what it does, what it takes, what it
-guarantees — *without naming the feature*. If you cannot, the contract is
-feature-shaped, and the second consumer will force it open. **Renaming the
-feature's nouns is not stating the contract in the component's vocabulary**:
-`store(ConfirmationPayload) -> id` described as "stores records by id" still fails.
-The question the wording cannot dodge — *would a second plausible consumer have to
-change this signature?* If yes it is feature-shaped, however it is phrased.
-
-The opposite error is equally real: this is not a licence to build a framework.
-Build for the need you have, at the size you need. What the rule constrains is the
-contract's **vocabulary and ownership**, not its scope — a five-line component with
-a clean contract satisfies it in full.
-
-## 4. Decide the unit of change
-
-A capability that needs building becomes **its own ANALYSIS, its own branch and its
-own closure** when ANY of these holds:
-
-- it will have more than one consumer, now or in the declared roadmap;
-- **it can ship before this feature does** — merged and adopted on its own cadence,
-  with the feature still unfinished. (Not "buildable and testable on its own": §3
-  requires that of every component, so reading it that way makes the default branch
-  below unreachable and puts every five-line helper through its own L3.) IN: a
-  storage layer another team can adopt next sprint while this feature is still in
-  design. OUT: a helper nobody can use until the feature that motivated it lands;
-- it carries its own risk surface: security, a public contract, a data model, or a
-  new dependency.
-
-Otherwise it is a **phase inside this feature's plan** — the first phase, before the
-feature consumes it — and it is still a component: own contract, own tests, never
-inlined into the feature's code path. **The split rule decides the paperwork; it
-never decides whether the component exists.**
-
-When it does become its own unit, each document names the other: the feature's
-ANALYSIS points at the component's, and the component's lists its consumers.
-
-## 5. Order
-
-The component is designed before the feature that consumes it, and normally built
-and tested before it too. A feature blocked on a capability it does not have is not
-"in progress" — it is a component task wearing a feature's name.
-
-## Anti-patterns
-
-- **Inlining** — the capability is implemented inside the feature's code path and no
-  component owns it. Symptom: the next feature that needs it must copy it or
-  refactor yours. This is the failure the pass exists to prevent.
-- **Feature-shaped platform** — the component exists, but its contract speaks the
-  feature's vocabulary. Symptom: the second consumer forces a contract change.
-- **Silent degradation** — a capability comes out MISSING, nobody wants to build it,
-  so the feature is quietly reshaped around what exists and ships as less than what
-  was asked. The reduced benefit must be surfaced to the user as a scope change and
-  recorded in the ANALYSIS; absorbing it silently is the Vision-divergence rule
-  broken one level down.
-- **Speculative platform** — a general framework built for a single known need.
-- **Paper ledger** — every row EXISTS, nothing named. Unfalsifiable, exactly like a
-  review that reports "I checked".
-- **Empty-map MISSING** — ruling a capability MISSING because the Component Map is
-  silent about it, in an area nobody has analyzed yet. The map's silence is
-  *unread*, not *empty*. On a project the methodology has just arrived in, the map
-  is nearly all silence, and this is the anti-pattern that duplicates the existing
-  codebase one component at a time.
-
-## Where the output is recorded
-
-Standalone: the `## Capability Ledger` section of the ANALYSIS (`templates.md`),
-immediately before `## Impact`, which it feeds — every INADEQUATE or MISSING row
-lands there as files to create or change. The closure review maps the ledger row by
-row (`review.md`).
-
-**A component that gets built lands in the `## Component Map`** of
-`strategic/architecture.md`, in the same closure — capability owned, contract,
-where it lives. This is the loop that makes the pass repeatable instead of
-per-session: the ledger asks the map what exists, so a component the map never
-learned about is one the next feature rules MISSING and builds a second time. The
-trigger is the component's birth, not a stack change (Write Triggers).
-
-**So does a component you merely discovered.** When the pass searches an unmapped
-area and finds an existing owner, write that row too, then `sdlc_check.py mark` the
-area you covered — **in that order, and never the mark without the rows.** Marking
-an area ANALYZED while its owners stay unwritten is the worst of both states: the
-area now looks read, so the map's silence there becomes groundable, and the next
-feature rules MISSING and builds a duplicate — lawfully. What a mark asserts is
-exactly this: *the area was read closely enough to name the capabilities it owns.*
-The map then grows by the feature that needed the knowledge instead of by an
-up-front sweep — the understanding was paid for either way, and this is the step
-that stops the next session paying for it again.
-
-Hybrid: the ledger goes in the `E-ISP`, above its Impacted Components map. A
-capability split out as its own unit of change gets its own `E-ISP`/`E-TDD`, and the
-feature's `E-ISP` names it as a dependency.
-
-## Mechanical backstops
-
-Prose is not enforcement; these are the checks that notice when the pass did not
-run or its output rotted. Both are **advisories** — printed as `[note]`, never
-counted as warnings, and never failing a build, **not even under `--strict`**. That
-is deliberate: the ceremony budget accepted for this pass was a signal, and a
-warning that reddens a pipeline is a gate under another name.
-
-- **Skipped pass**: `validate` notes an L3 ANALYSIS started on/after 2026-07-28
-  that lacks `## Capability Ledger`. Grandfathered by `start_date` alone —
-  analyses born before the pass existed never nag — and deliberately NOT by
-  status: closure flips the ANALYSIS to COMPLETED *before* `check` runs, so a
-  status filter would silence the backstop at the exact moment the process
-  mandates the validator.
-- **Rotting map**: `validate` resolves every path-shaped ref in the Component
-  Map's `Where` column — a path that no longer exists, or a `#symbol` no longer
-  present as a whole word in the file, is flagged; so is a map whose rows carry
-  no checkable path at all, or whose header has no `Where` column (an inert check
-  reported as a clean one is the same defect as an unread map reported as empty).
-  This is the map's equivalent of the guides' `source_hash`, with the same honest
-  limit: it proves the ref resolves, never that the row still describes the
-  component correctly.
-- **A mark nobody paid for**: `validate` notes an area the audit plan marks
-  ANALYZED that owns no Component Map row. Marking is one cheap command and it is
-  what converts the map's silence into a groundable MISSING — so this is the other
-  half of the loop, the check that a mark asserted something real.
-- **Adherence** (non-gating, **skill development only** — `evals/` is not shipped
-  in the installed package): `architect_rules_before_impact.md` runs the pass
-  cold; `unmapped_never_grounds_missing.md` sets the brownfield trap — an existing
-  component in a PENDING area, where ruling MISSING from the map's silence is the
-  failure.
-
-## Below L3
-
-L1 and L2 do not run this pass. A capability discovered MISSING during L2 work is
-itself an escalation trigger: stop, reclassify to L3, declare it (Rule Zero). "The
-component was not there" is never a reason to build it inside an L2.
+# The Architect Pass
+
+Applies at L3, in phase 3, AFTER the spec elicitation and BEFORE the Impact is
+drafted. It answers the one question the Impact cannot ask: *does the system
+already have the components and services this feature needs?*
+
+Why it exists: **a feature is not a unit of construction.** Left alone, an agent
+designs the feature and builds whatever it lacks inside the feature's own code
+path — so no component owns the capability, the next feature that needs it
+rebuilds it differently, and the platform accretes feature-shaped code nobody can
+reuse. That is myopia one level above the file: the change is complete, the tests
+pass, and the architecture is worse.
+
+## 1. State the feature as capabilities, not as files
+
+Write what the system must be able to DO for this feature to exist — "persist a
+draft across sessions", "notify a third party asynchronously", "authorize per
+tenant". A capability is a verb over a domain noun. It names no file, no class and
+no library: **that** is the decoupling. Files come later, in the Impact.
+
+Two or three capabilities is a normal feature. When the list has one obvious entry
+and it plainly exists, say so in one line **under the `## Capability Ledger`
+heading, still naming the component and where it lives**, and move on — this pass
+is a question to answer, not a form to fill. The heading is what makes a cheap
+answer distinguishable from a skipped pass; a bare "everything already exists"
+names nothing and is the **Paper ledger** anti-pattern, not the licence.
+
+## 2. Rule each capability against the platform
+
+One verdict per capability:
+
+| Verdict | Meaning | What the row must carry |
+|---|---|---|
+| **EXISTS** | a component already owns this capability and covers the need | the component, where it lives (path / symbol), and the one guarantee you re-read it to confirm |
+| **INADEQUATE** | a component owns it but does not cover the need | the same, plus the gap in one line |
+| **MISSING** | no component owns it | the terms you searched, the tool, and the areas covered |
+
+Read the **`## Component Map`** in `strategic/architecture.md` first — the project's
+inventory of what owns which capability, kept so this pass does not re-derive the
+platform from source every session.
+
+**The map is a cache of evidence somebody already paid for. It lowers the COST of a
+verdict, never the STANDARD of one.** Every verdict carries the same evidence
+whether the map answered it or not; a hit means the search is already written down,
+a miss means you pay full price. Reading a row does not excuse you from checking
+that it is still true — the map is the index, the code is the evidence.
+
+**Its silence is unread, not empty.** The map covers only the areas `audit/
+audit_plan.md` marks ANALYZED — and that state is a claim someone made, not a fact
+the tooling verified: marking asserts *the area was read closely enough to name the
+capabilities it owns*, so an area marked after two greps is a false ANALYZED and
+the person who wrote it owns the duplicate that follows. In an area still PENDING —
+or SKIPPED, or absent from the plan entirely — **the map can never ground a MISSING
+verdict.** Nothing there has been looked at yet, and "the inventory does not mention
+it" is the reasoning that builds a second copy of a component that already exists.
+
+**Searching for an owner** is text search first, symbol-graph second — in that
+order, because you are looking for a name you do not know yet, and a call-hierarchy
+tool needs a resolved symbol as *input*. Grep the repository (minus SKIPPED areas)
+for the domain noun, at least two plausible synonyms, and the verb; then use the
+symbol-graph tool to confirm or dismiss the candidates the search surfaced.
+
+**The floor for a MISSING** is about triage, not term count: every hit that lands in
+an unmapped area gets opened, or the MISSING is **provisional** and says so in its
+row. Record what you ran — terms, tool, areas — and stop when the terms are
+exhausted and no candidate remains unopened. A provisional MISSING is honest and
+cheap; an unfalsifiable one is the same defect as an EXISTS with no symbol named.
+
+**Understanding is never deferred; only WRITING the map is.** You may leave the rest
+of the repository unmapped and grow the inventory feature by feature — you may not
+leave unexamined anything this change touches or depends on. That blast zone is
+understood now, at full standard, mapped or not. The incremental licence is about
+the artifact, never about the comprehension.
+
+Ground every verdict. An EXISTS with no named symbol is an assumption wearing a
+verdict's clothes, and it is the row that breaks in implementation. A MISSING
+declared without a real search is how duplication enters — the component may be
+there under a name you did not guess. This is the DRY check at architecture level.
+
+## 3. Design what is missing as a component, not as feature internals
+
+INADEQUATE and MISSING produce design work of their own, governed by one rule:
+
+**The component's contract is stated in the component's own vocabulary. The feature
+is one consumer, never the owner.**
+
+The test is mechanical: write the contract — what it does, what it takes, what it
+guarantees — *without naming the feature*. If you cannot, the contract is
+feature-shaped, and the second consumer will force it open. **Renaming the
+feature's nouns is not stating the contract in the component's vocabulary**:
+`store(ConfirmationPayload) -> id` described as "stores records by id" still fails.
+The question the wording cannot dodge — *would a second plausible consumer have to
+change this signature?* If yes it is feature-shaped, however it is phrased.
+
+The opposite error is equally real: this is not a licence to build a framework.
+Build for the need you have, at the size you need. What the rule constrains is the
+contract's **vocabulary and ownership**, not its scope — a five-line component with
+a clean contract satisfies it in full.
+
+## 4. Decide the unit of change
+
+A capability that needs building becomes **its own ANALYSIS, its own branch and its
+own closure** when ANY of these holds:
+
+- it will have more than one consumer, now or in the declared roadmap;
+- **it can ship before this feature does** — merged and adopted on its own cadence,
+  with the feature still unfinished. (Not "buildable and testable on its own": §3
+  requires that of every component, so reading it that way makes the default branch
+  below unreachable and puts every five-line helper through its own L3.) IN: a
+  storage layer another team can adopt next sprint while this feature is still in
+  design. OUT: a helper nobody can use until the feature that motivated it lands;
+- it carries its own risk surface: security, a public contract, a data model, or a
+  new dependency.
+
+Otherwise it is a **phase inside this feature's plan** — the first phase, before the
+feature consumes it — and it is still a component: own contract, own tests, never
+inlined into the feature's code path. **The split rule decides the paperwork; it
+never decides whether the component exists.**
+
+When it does become its own unit, each document names the other: the feature's
+ANALYSIS points at the component's, and the component's lists its consumers.
+
+## 5. Order
+
+The component is designed before the feature that consumes it, and normally built
+and tested before it too. A feature blocked on a capability it does not have is not
+"in progress" — it is a component task wearing a feature's name.
+
+## Anti-patterns
+
+- **Inlining** — the capability is implemented inside the feature's code path and no
+  component owns it. Symptom: the next feature that needs it must copy it or
+  refactor yours. This is the failure the pass exists to prevent.
+- **Feature-shaped platform** — the component exists, but its contract speaks the
+  feature's vocabulary. Symptom: the second consumer forces a contract change.
+- **Silent degradation** — a capability comes out MISSING, nobody wants to build it,
+  so the feature is quietly reshaped around what exists and ships as less than what
+  was asked. The reduced benefit must be surfaced to the user as a scope change and
+  recorded in the ANALYSIS; absorbing it silently is the Vision-divergence rule
+  broken one level down.
+- **Speculative platform** — a general framework built for a single known need.
+- **Paper ledger** — every row EXISTS, nothing named. Unfalsifiable, exactly like a
+  review that reports "I checked".
+- **Empty-map MISSING** — ruling a capability MISSING because the Component Map is
+  silent about it, in an area nobody has analyzed yet. The map's silence is
+  *unread*, not *empty*. On a project the methodology has just arrived in, the map
+  is nearly all silence, and this is the anti-pattern that duplicates the existing
+  codebase one component at a time.
+
+## Where the output is recorded
+
+Standalone: the `## Capability Ledger` section of the ANALYSIS (`templates.md`),
+immediately before `## Impact`, which it feeds — every INADEQUATE or MISSING row
+lands there as files to create or change. The closure review maps the ledger row by
+row (`review.md`).
+
+**A component that gets built lands in the `## Component Map`** of
+`strategic/architecture.md`, in the same closure — capability owned, contract,
+where it lives. This is the loop that makes the pass repeatable instead of
+per-session: the ledger asks the map what exists, so a component the map never
+learned about is one the next feature rules MISSING and builds a second time. The
+trigger is the component's birth, not a stack change (Write Triggers).
+
+**So does a component you merely discovered.** When the pass searches an unmapped
+area and finds an existing owner, write that row too, then `sdlc_check.py mark` the
+area you covered — **in that order, and never the mark without the rows.** Marking
+an area ANALYZED while its owners stay unwritten is the worst of both states: the
+area now looks read, so the map's silence there becomes groundable, and the next
+feature rules MISSING and builds a duplicate — lawfully. What a mark asserts is
+exactly this: *the area was read closely enough to name the capabilities it owns.*
+The map then grows by the feature that needed the knowledge instead of by an
+up-front sweep — the understanding was paid for either way, and this is the step
+that stops the next session paying for it again.
+
+Hybrid: the ledger goes in the `E-ISP`, above its Impacted Components map. A
+capability split out as its own unit of change gets its own `E-ISP`/`E-TDD`, and the
+feature's `E-ISP` names it as a dependency.
+
+## Mechanical backstops
+
+Prose is not enforcement; these are the checks that notice when the pass did not
+run or its output rotted. Both are **advisories** — printed as `[note]`, never
+counted as warnings, and never failing a build, **not even under `--strict`**. That
+is deliberate: the ceremony budget accepted for this pass was a signal, and a
+warning that reddens a pipeline is a gate under another name.
+
+- **Skipped pass**: `validate` notes an L3 ANALYSIS started on/after 2026-07-28
+  that lacks `## Capability Ledger`. Grandfathered by `start_date` alone —
+  analyses born before the pass existed never nag — and deliberately NOT by
+  status: closure flips the ANALYSIS to COMPLETED *before* `check` runs, so a
+  status filter would silence the backstop at the exact moment the process
+  mandates the validator.
+- **Rotting map**: `validate` resolves every path-shaped ref in the Component
+  Map's `Where` column — a path that no longer exists, or a `#symbol` no longer
+  present as a whole word in the file, is flagged; so is a map whose rows carry
+  no checkable path at all, or whose header has no `Where` column (an inert check
+  reported as a clean one is the same defect as an unread map reported as empty).
+  This is the map's equivalent of the guides' `source_hash`, with the same honest
+  limit: it proves the ref resolves, never that the row still describes the
+  component correctly.
+- **A mark nobody paid for**: `validate` notes an area the audit plan marks
+  ANALYZED that owns no Component Map row. Marking is one cheap command and it is
+  what converts the map's silence into a groundable MISSING — so this is the other
+  half of the loop, the check that a mark asserted something real.
+- **Adherence** (non-gating, **skill development only** — `evals/` is not shipped
+  in the installed package): `architect_rules_before_impact.md` runs the pass
+  cold; `unmapped_never_grounds_missing.md` sets the brownfield trap — an existing
+  component in a PENDING area, where ruling MISSING from the map's silence is the
+  failure.
+
+## Below L3
+
+L1 and L2 do not run this pass. A capability discovered MISSING during L2 work is
+itself an escalation trigger: stop, reclassify to L3, declare it (Rule Zero). "The
+component was not there" is never a reason to build it inside an L2.

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.