diff --git a/docs/all-anchors.adoc b/docs/all-anchors.adoc index 38c6c67..efa2d6e 100644 --- a/docs/all-anchors.adoc +++ b/docs/all-anchors.adoc @@ -161,6 +161,8 @@ include::anchors/timtowtdi.adoc[leveloffset=+2] include::anchors/socratic-method.adoc[leveloffset=+2] +include::anchors/xy-problem.adoc[leveloffset=+2] + <<< == Documentation @@ -193,8 +195,12 @@ include::anchors/what-qualifies-as-a-semantic-anchor.adoc[leveloffset=+2] include::anchors/chain-of-thought.adoc[leveloffset=+2] +include::anchors/decisional-balance-sheet.adoc[leveloffset=+2] + include::anchors/devils-advocate.adoc[leveloffset=+2] +include::anchors/double-diamond.adoc[leveloffset=+2] + include::anchors/feynman-technique.adoc[leveloffset=+2] include::anchors/five-whys.adoc[leveloffset=+2] @@ -205,16 +211,22 @@ include::anchors/occams-razor.adoc[leveloffset=+2] include::anchors/what-would-chuck-norris-do.adoc[leveloffset=+2] +include::anchors/xy-problem.adoc[leveloffset=+2] + <<< == Requirements Engineering include::anchors/cockburn-use-cases.adoc[leveloffset=+2] +include::anchors/double-diamond.adoc[leveloffset=+2] + include::anchors/ears-requirements.adoc[leveloffset=+2] include::anchors/invest.adoc[leveloffset=+2] +include::anchors/kano-model.adoc[leveloffset=+2] + include::anchors/moscow.adoc[leveloffset=+2] include::anchors/prd.adoc[leveloffset=+2] @@ -277,10 +289,18 @@ include::anchors/spc.adoc[leveloffset=+2] include::anchors/cynefin-framework.adoc[leveloffset=+2] +include::anchors/decisional-balance-sheet.adoc[leveloffset=+2] + +include::anchors/hoshin-kanri.adoc[leveloffset=+2] + include::anchors/impact-mapping.adoc[leveloffset=+2] include::anchors/jobs-to-be-done.adoc[leveloffset=+2] +include::anchors/kano-model.adoc[leveloffset=+2] + +include::anchors/kotter-8-step-change-model.adoc[leveloffset=+2] + include::anchors/mvp.adoc[leveloffset=+2] include::anchors/pert.adoc[leveloffset=+2] @@ -336,3 +356,17 @@ include::anchors/test-double-stub.adoc[leveloffset=+2] include::anchors/testing-pyramid.adoc[leveloffset=+2] <<< + +== Workflow + +include::anchors/workflow-architecture-documentation.adoc[leveloffset=+2] + +include::anchors/workflow-code-review.adoc[leveloffset=+2] + +include::anchors/workflow-requirements-to-spec.adoc[leveloffset=+2] + +include::anchors/workflow-strategic-analysis.adoc[leveloffset=+2] + +include::anchors/workflow-tdd-clean-architecture.adoc[leveloffset=+2] + +<<< diff --git a/docs/brownfield-workflow.adoc b/docs/brownfield-workflow.adoc index 13b8fbf..1a39305 100644 --- a/docs/brownfield-workflow.adoc +++ b/docs/brownfield-workflow.adoc @@ -66,7 +66,7 @@ The prompts in this phase are also packaged as an installable Claude Code Skill. === Phase 1: Build the Question Tree -Start with five high-level questions about the bounded context and decompose them recursively. Use Semantic Anchors as decomposition guides: *arc42* for architecture, *Cockburn Use Cases* for specification, *ISO 25010* for quality, *Nygard ADRs* for decisions. +Start with five root questions about the bounded context. Their *second level is fixed*: every run emits the same prescribed set of sub-questions — the six PRD elements (Q1.1–Q1.6), six specification categories (Q2.1–Q2.6), the twelve arc42 chapters (Q3.1–Q3.12), the eight ISO/IEC 25010 characteristics plus a priority question (Q4.1–Q4.9), and five risk categories (Q5.1–Q5.5). Free, code-driven decomposition applies only *below* that fixed level. The fixed level keeps Q-IDs stable — Q3.7 is always the Deployment View — so trees from different runs can be diffed node-by-node. Each leaf in the tree is either `[ANSWERED]` (with code evidence: file, function, line) or `[OPEN]` (with Category and Ask role). The output is two AsciiDoc files: `QUESTION_TREE.adoc` (full reasoning trace) and `OPEN_QUESTIONS.adoc` (handoff document, grouped by role). @@ -83,26 +83,33 @@ recursive question refinement, before any documentation is written. Process: -1. Start with five high-level questions about the bounded context: +1. Start with five root questions about the bounded context: Q1 What problem does this bounded context solve, and for whom? Q2 What is the specification of this bounded context? Q3 What is the architecture of this bounded context? Q4 What quality goals drive the design? Q5 What risks and technical debt exist? -2. Decompose each question recursively. Use these Semantic Anchors as - decomposition guides: - - arc42 — 12 sub-questions for architecture (Q3 branch) - - Cockburn Use Cases — Primary Actor, Trigger, Main Success Scenario, - Extensions, Postconditions for specification (Q2 branch) - - ISO/IEC 25010 — 8 quality characteristics for quality goals (Q4 branch) - - Nygard ADRs — Context, Decision, Status, Consequences for design - rationale (Q3.9 branch) - Stop decomposing when a question is precise enough to be answered with a - single piece of code evidence or a single fact from a stakeholder. - -3. Assign a hierarchical Q-ID to every node (Q1, Q1.2, Q1.2.3, ...) so that - later documentation can cite back to it. +2. The second level of the tree is FIXED, not free. Emit exactly these + nodes, in this order, even when a node's only leaf is [OPEN] or + [ANSWERED: not applicable]: + Q1.1-Q1.6 product identity, primary users, channels, why-built, + success metrics, segment priority + Q2.1-Q2.6 actors, use-case catalog, per-interface system specs, + data/entity model, acceptance criteria, cross-cutting + business rules + Q3.1-Q3.12 the twelve arc42 chapters, in arc42 order + Q4.1-Q4.8 the eight ISO/IEC 25010 characteristics; + Q4.9 which characteristic has priority + Q5.1-Q5.5 technical debt, security risks, operational risks, + dependency/supply-chain risks, scaling/performance risks + +3. Below the fixed second level, decompose freely and code-driven. Stop + when a leaf is small enough to answer from a single piece of code + evidence, or to pose as a single precise question to a stakeholder. + Third-level depth varies between runs — that is expected. Q-IDs are + stable: Q3.7 is always the Deployment View, in every run, so trees + from different runs can be diffed node-by-node. 4. For each leaf, classify it: @@ -129,7 +136,9 @@ Process: OPEN_QUESTIONS.adoc - Only the [OPEN] leaves, copied verbatim from QUESTION_TREE.adoc - - Grouped by Ask role (one section per role) + - Always one section per Ask role (Product Owner, Architect, + Developer, Domain Expert, Operations) — emit every section even + when it is empty ("No open questions for this role") - Each question short enough to be answered in 1-3 sentences Do not write any other documentation in this phase. Phase 2 will synthesize @@ -253,7 +262,7 @@ Stable code that nobody touches does not need specs. |link:#/anchor/domain-driven-design[DDD] |Theory Recovery (Phase 1) -|`You have access to [bounded context path]. No documentation exists. Build a Question Tree by recursively refining 5 questions: Problem/Users, Specification, Architecture, Quality Goals, Risks. Each leaf: [ANSWERED] with code evidence or [OPEN] with Category and Ask role.` +|`You have access to [bounded context path]. No documentation exists. Build a Question Tree: 5 root questions (Problem/Users, Specification, Architecture, Quality Goals, Risks), each with a FIXED second level (Q1.1-Q5.5: 6 PRD elements, 6 spec categories, 12 arc42 chapters, 8 ISO 25010 characteristics + priority, 5 risk categories); free decomposition only below it. Each leaf: [ANSWERED] with file:line evidence or [OPEN] with Category and Ask role.` |link:#/anchor/arc42[arc42], link:#/anchor/cockburn-use-cases[Cockburn], link:#/anchor/iso-25010[ISO 25010], link:#/anchor/nygard-adrs[Nygard ADR] |Team Answers diff --git a/docs/brownfield-workflow.de.adoc b/docs/brownfield-workflow.de.adoc index 6d38eea..d26c1f4 100644 --- a/docs/brownfield-workflow.de.adoc +++ b/docs/brownfield-workflow.de.adoc @@ -64,7 +64,7 @@ Die Prompts dieser Phase sind auch als installierbarer Claude Code Skill verpack === Phase 1: Question Tree aufbauen -Mit fünf Top-Level-Fragen zum Bounded Context starten und sie rekursiv zerlegen. Semantic Anchors als Zerlegungs-Heuristiken einsetzen: *arc42* für Architektur, *Cockburn Use Cases* für Spezifikation, *ISO 25010* für Qualität, *Nygard ADRs* für Entscheidungen. +Mit fünf Wurzelfragen zum Bounded Context starten. Ihre *zweite Ebene ist fix*: jeder Lauf erzeugt denselben vorgegebenen Satz an Unterfragen — die sechs PRD-Elemente (Q1.1–Q1.6), sechs Spezifikationskategorien (Q2.1–Q2.6), die zwölf arc42-Kapitel (Q3.1–Q3.12), die acht ISO/IEC-25010-Merkmale plus eine Prioritätsfrage (Q4.1–Q4.9) und fünf Risikokategorien (Q5.1–Q5.5). Freie, code-getriebene Zerlegung gilt nur *unterhalb* dieser fixen Ebene. Die fixe Ebene hält Q-IDs stabil — Q3.7 ist immer die Verteilungssicht —, sodass Bäume verschiedener Läufe Knoten für Knoten verglichen werden können. Jedes Blatt im Baum ist entweder `[ANSWERED]` (mit Code-Evidenz: Datei, Funktion, Zeile) oder `[OPEN]` (mit Category und Ask-Rolle). Der Output sind zwei AsciiDoc-Dateien: `QUESTION_TREE.adoc` (vollständige Begründungs-Spur) und `OPEN_QUESTIONS.adoc` (Handoff-Dokument, nach Rolle gruppiert). @@ -81,26 +81,33 @@ recursive question refinement, before any documentation is written. Process: -1. Start with five high-level questions about the bounded context: +1. Start with five root questions about the bounded context: Q1 What problem does this bounded context solve, and for whom? Q2 What is the specification of this bounded context? Q3 What is the architecture of this bounded context? Q4 What quality goals drive the design? Q5 What risks and technical debt exist? -2. Decompose each question recursively. Use these Semantic Anchors as - decomposition guides: - - arc42 — 12 sub-questions for architecture (Q3 branch) - - Cockburn Use Cases — Primary Actor, Trigger, Main Success Scenario, - Extensions, Postconditions for specification (Q2 branch) - - ISO/IEC 25010 — 8 quality characteristics for quality goals (Q4 branch) - - Nygard ADRs — Context, Decision, Status, Consequences for design - rationale (Q3.9 branch) - Stop decomposing when a question is precise enough to be answered with a - single piece of code evidence or a single fact from a stakeholder. - -3. Assign a hierarchical Q-ID to every node (Q1, Q1.2, Q1.2.3, ...) so that - later documentation can cite back to it. +2. The second level of the tree is FIXED, not free. Emit exactly these + nodes, in this order, even when a node's only leaf is [OPEN] or + [ANSWERED: not applicable]: + Q1.1-Q1.6 product identity, primary users, channels, why-built, + success metrics, segment priority + Q2.1-Q2.6 actors, use-case catalog, per-interface system specs, + data/entity model, acceptance criteria, cross-cutting + business rules + Q3.1-Q3.12 the twelve arc42 chapters, in arc42 order + Q4.1-Q4.8 the eight ISO/IEC 25010 characteristics; + Q4.9 which characteristic has priority + Q5.1-Q5.5 technical debt, security risks, operational risks, + dependency/supply-chain risks, scaling/performance risks + +3. Below the fixed second level, decompose freely and code-driven. Stop + when a leaf is small enough to answer from a single piece of code + evidence, or to pose as a single precise question to a stakeholder. + Third-level depth varies between runs — that is expected. Q-IDs are + stable: Q3.7 is always the Deployment View, in every run, so trees + from different runs can be diffed node-by-node. 4. For each leaf, classify it: @@ -127,7 +134,9 @@ Process: OPEN_QUESTIONS.adoc - Only the [OPEN] leaves, copied verbatim from QUESTION_TREE.adoc - - Grouped by Ask role (one section per role) + - Always one section per Ask role (Product Owner, Architect, + Developer, Domain Expert, Operations) — emit every section even + when it is empty ("No open questions for this role") - Each question short enough to be answered in 1-3 sentences Do not write any other documentation in this phase. Phase 2 will synthesize @@ -251,7 +260,7 @@ Stabiler Code, den niemand anfasst, braucht keine Specs. |link:#/anchor/domain-driven-design[DDD] |Theory Recovery (Phase 1) -|`You have access to [bounded context path]. No documentation exists. Build a Question Tree by recursively refining 5 questions: Problem/Users, Specification, Architecture, Quality Goals, Risks. Each leaf: [ANSWERED] with code evidence or [OPEN] with Category and Ask role.` +|`You have access to [bounded context path]. No documentation exists. Build a Question Tree: 5 root questions (Problem/Users, Specification, Architecture, Quality Goals, Risks), each with a FIXED second level (Q1.1-Q5.5: 6 PRD elements, 6 spec categories, 12 arc42 chapters, 8 ISO 25010 characteristics + priority, 5 risk categories); free decomposition only below it. Each leaf: [ANSWERED] with file:line evidence or [OPEN] with Category and Ask role.` |link:#/anchor/arc42[arc42], link:#/anchor/cockburn-use-cases[Cockburn], link:#/anchor/iso-25010[ISO 25010], link:#/anchor/nygard-adrs[Nygard ADR] |Team Answers diff --git a/docs/socratic-recovery-skill.adoc b/docs/socratic-recovery-skill.adoc index 0ee80b0..d872835 100644 --- a/docs/socratic-recovery-skill.adoc +++ b/docs/socratic-recovery-skill.adoc @@ -9,7 +9,7 @@ Recovers documentation from a brownfield codebase without hallucinating the part === Phase 1 — Build the Question Tree -The skill prompts the LLM to recursively decompose five questions about a bounded context (Problem/Users, Specification, Architecture, Quality Goals, Risks). Each leaf is classified: +The skill prompts the LLM to build a Question Tree from five root questions about a bounded context (Problem/Users, Specification, Architecture, Quality Goals, Risks). Their second level is fixed — every run emits the same enumerated nodes (Q1.1–Q5.5: six PRD elements, six specification categories, the twelve arc42 chapters, the eight ISO/IEC 25010 characteristics plus a priority question, five risk categories), so Q-IDs are stable and trees from different runs can be diffed node-by-node. Free, code-driven decomposition happens only below that fixed level. Each leaf is classified: * `[ANSWERED]` -- the LLM found it in the code, with `:` evidence * `[OPEN]` -- the answer is not derivable from code; tagged with a Category and the role that must answer (Product Owner, Architect, Developer, Domain Expert, Operations) @@ -190,13 +190,13 @@ Any AI assistant that accepts a system prompt or custom instructions can use thi | The Phase 2 prompt producing PRD, Cockburn use cases, arc42, and Nygard ADRs | `references/arc42.md` -| arc42's 12 sections as Q3 decomposition heuristic +| arc42's 12 chapters as the fixed Q3.1–Q3.12 nodes | `references/cockburn-use-cases.md` -| Fully Dressed fields as Q2 sub-questions; persona vs system use cases +| Fully Dressed fields as use-case leaves; persona vs system use cases | `references/iso-25010.md` -| 8 quality characteristics as Q4 sub-questions; mechanism-vs-target split +| 8 quality characteristics as the fixed Q4.1–Q4.8 nodes; mechanism-vs-target split | `references/nygard-adrs.md` | ADR fields as Q3.9 sub-tree; what makes a decision architecturally significant; Pugh-matrix guidance diff --git a/docs/socratic-recovery-skill.de.adoc b/docs/socratic-recovery-skill.de.adoc index 65c9ad5..c0024c3 100644 --- a/docs/socratic-recovery-skill.de.adoc +++ b/docs/socratic-recovery-skill.de.adoc @@ -9,7 +9,7 @@ Stellt Dokumentation aus einem Brownfield-Codebase wieder her, ohne die Lücken === Phase 1 — Question Tree aufbauen -Der Skill weist das LLM an, fünf Fragen zum Bounded Context (Problem/User, Spezifikation, Architektur, Qualitätsziele, Risiken) rekursiv zu zerlegen. Jedes Blatt wird klassifiziert: +Der Skill weist das LLM an, aus fünf Wurzelfragen zum Bounded Context (Problem/User, Spezifikation, Architektur, Qualitätsziele, Risiken) einen Question Tree zu bauen. Ihre zweite Ebene ist fix — jeder Lauf erzeugt dieselben enumerierten Knoten (Q1.1–Q5.5: sechs PRD-Elemente, sechs Spezifikationskategorien, die zwölf arc42-Kapitel, die acht ISO/IEC-25010-Merkmale plus eine Prioritätsfrage, fünf Risikokategorien), sodass Q-IDs stabil sind und Bäume verschiedener Läufe Knoten für Knoten verglichen werden können. Freie, code-getriebene Zerlegung passiert nur unterhalb dieser fixen Ebene. Jedes Blatt wird klassifiziert: * `[ANSWERED]` -- das LLM hat es im Code gefunden, mit `:`-Evidenz * `[OPEN]` -- die Antwort steckt nicht im Code; mit Category und der Rolle markiert, die antworten muss (Product Owner, Architect, Developer, Domain Expert, Operations) @@ -190,13 +190,13 @@ Jeder Assistent, der einen System-Prompt oder Custom Instructions akzeptiert, ka | Der Phase-2-Prompt, der PRD, Cockburn Use Cases, arc42 und Nygard-ADRs erzeugt | `references/arc42.md` -| arc42 12 Sektionen als Q3-Zerlegungs-Heuristik +| arc42 12 Kapitel als die fixen Knoten Q3.1–Q3.12 | `references/cockburn-use-cases.md` -| Fully-Dressed-Felder als Q2-Subfragen; Persona- vs. System-Use-Cases +| Fully-Dressed-Felder als Use-Case-Blätter; Persona- vs. System-Use-Cases | `references/iso-25010.md` -| 8 Qualitätsmerkmale als Q4-Subfragen; Mechanismus-vs-Target-Trennung +| 8 Qualitätsmerkmale als die fixen Knoten Q4.1–Q4.8; Mechanismus-vs-Target-Trennung | `references/nygard-adrs.md` | ADR-Felder als Q3.9-Sub-Tree; was eine Entscheidung architektonisch signifikant macht; Pugh-Matrix-Leitfaden diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md index c1ef585..9abd8fb 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md @@ -71,19 +71,22 @@ The fix: model the gaps explicitly. Every question about the system is either `[ ### Phase 1: Build the Question Tree -Use [prompts/phase-1-question-tree.md](prompts/phase-1-question-tree.md). Adapt the bounded-context path and any domain-specific Q1 examples; do not change the leaf classification, Q-ID scheme, or output files. +Use [prompts/phase-1-question-tree.md](prompts/phase-1-question-tree.md). Adapt the bounded-context path and the Q1-Q5 wording; do not change the fixed second level, the leaf classification, the Q-ID scheme, or the output files. Outputs: - `QUESTION_TREE.adoc` — the full hierarchical reasoning trace - `OPEN_QUESTIONS.adoc` — only the `[OPEN]` leaves, grouped by Ask role -Decomposition heuristics — use these Semantic Anchors as guides, not as rigid templates: +The five root questions decompose into a **fixed second level** — the same enumerated node set on every run, so Q-IDs are stable and trees from different runs can be diffed node-by-node. Free, code-driven decomposition applies only *below* the fixed level. The fixed nodes: -- **arc42** — 12 architecture sub-questions (Q3 branch). See [references/arc42.md](references/arc42.md). -- **Cockburn Use Cases** — specification structure (Q2 branch). See [references/cockburn-use-cases.md](references/cockburn-use-cases.md). -- **ISO/IEC 25010** — 8 quality characteristics (Q4 branch). See [references/iso-25010.md](references/iso-25010.md). -- **Nygard ADRs** — design-rationale capture (Q3.9 branch). See [references/nygard-adrs.md](references/nygard-adrs.md). +- **Q1.1–Q1.6** — product identity, primary users, channels, why-built, success metrics, segment priority. +- **Q2.1–Q2.6** — actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules. See [references/cockburn-use-cases.md](references/cockburn-use-cases.md). +- **Q3.1–Q3.12** — the twelve arc42 chapters, in arc42 order. See [references/arc42.md](references/arc42.md). Design rationale lives in the Q3.9 chapter — see [references/nygard-adrs.md](references/nygard-adrs.md). +- **Q4.1–Q4.8** — the eight ISO/IEC 25010 characteristics; **Q4.9** — which characteristic has priority. See [references/iso-25010.md](references/iso-25010.md). +- **Q5.1–Q5.5** — technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks. + +Every fixed node is emitted even when its only leaf is `[OPEN]` or `[ANSWERED: not applicable]`. Leaf classification rules and Q-ID scheme: [references/output-schema.md](references/output-schema.md). diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-1-question-tree.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-1-question-tree.md index 4229c25..6059df7 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-1-question-tree.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-1-question-tree.md @@ -1,6 +1,6 @@ # Phase 1 Prompt: Build the Question Tree -Copy the block below into a session that has read access to the bounded context. Replace `[bounded context path]` with the actual path. Adapt the Q1-Q5 examples if your domain has different starting concerns, but do not change the leaf classification, Q-ID scheme, or output files. +Copy the block below into a session that has read access to the bounded context. Replace `[bounded context path]` with the actual path. Adapt the Q1-Q5 wording if your domain has different starting concerns, but do not change the fixed second level, the leaf classification, the Q-ID scheme, or the output files. ``` You are performing Socratic Code-Theory Recovery on a brownfield bounded @@ -11,26 +11,34 @@ recursive question refinement, before any documentation is written. Process: -1. Start with five high-level questions about the bounded context: +1. Start with five root questions about the bounded context: Q1 What problem does this bounded context solve, and for whom? Q2 What is the specification of this bounded context? Q3 What is the architecture of this bounded context? Q4 What quality goals drive the design? Q5 What risks and technical debt exist? -2. Decompose each question recursively. Use these Semantic Anchors as - decomposition guides: - - arc42 — 12 sub-questions for architecture (Q3 branch) - - Cockburn Use Cases — Primary Actor, Trigger, Main Success Scenario, - Extensions, Postconditions for specification (Q2 branch) - - ISO/IEC 25010 — 8 quality characteristics for quality goals (Q4 branch) - - Nygard ADRs — Context, Decision, Status, Consequences for design - rationale (Q3.9 branch) - Stop decomposing when a question is precise enough to be answered with a - single piece of code evidence or a single fact from a stakeholder. - -3. Assign a hierarchical Q-ID to every node (Q1, Q1.2, Q1.2.3, ...) so that - later documentation can cite back to it. +2. The second level of the tree is FIXED, not free. Emit exactly these + nodes, in this order, even when a node's only leaf is [OPEN] or + [ANSWERED: not applicable]: + Q1.1-Q1.6 product identity, primary users, channels, why-built, + success metrics, segment priority + Q2.1-Q2.6 actors, use-case catalog, per-interface system specs, + data/entity model, acceptance criteria, cross-cutting + business rules + Q3.1-Q3.12 the twelve arc42 chapters, in arc42 order + Q4.1-Q4.8 the eight ISO/IEC 25010 characteristics; + Q4.9 which characteristic has priority + Q5.1-Q5.5 technical debt, security risks, operational risks, + dependency/supply-chain risks, scaling/performance risks + +3. Below the fixed second level, decompose freely and code-driven. Stop + when a leaf is small enough to answer from a single piece of code + evidence, or to pose as a single precise question to a stakeholder. + Third-level depth varies between runs + — that is expected. Q-IDs are stable: Q3.7 is always the Deployment + View, in every run, so trees from different runs can be diffed + node-by-node. 4. For each leaf, classify it: @@ -57,7 +65,9 @@ Process: OPEN_QUESTIONS.adoc - Only the [OPEN] leaves, copied verbatim from QUESTION_TREE.adoc - - Grouped by Ask role (one section per role) + - Always one section per Ask role (Product Owner, Architect, + Developer, Domain Expert, Operations) — emit every section even + when it is empty ("No open questions for this role") - Each question short enough to be answered in 1-3 sentences Do not write any other documentation in this phase. Phase 2 will synthesize diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-2-synthesize.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-2-synthesize.md index a8370a9..14e49dc 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-2-synthesize.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-2-synthesize.md @@ -51,9 +51,10 @@ Produce four artifacts: Rules for traceability: - The synthesized documentation must be self-contained. The Question Tree - is temporary scaffolding — it is renumbered on every re-run — so Q-IDs - must NOT appear in the output. While synthesizing, trace every claim - back to a leaf: each claim must come from an [ANSWERED] leaf or an + is a temporary intermediate artifact — its fixed second level is stable, + but third-level Q-IDs are run-specific and the tree is not shipped — so + Q-IDs must NOT appear in the output. While synthesizing, trace every + claim back to a leaf: each claim must come from an [ANSWERED] leaf or an answered [OPEN] leaf. This tracing is a build-time check, not something written into the documents. - A claim backed by an [ANSWERED] leaf cites the code evidence from that diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/arc42.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/arc42.md index b925422..8bfa5c4 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/arc42.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/arc42.md @@ -1,6 +1,6 @@ # arc42 — Decomposition Guide for Q3 (Architecture) -arc42 is a 12-section template for documenting software architecture (Gernot Starke, Peter Hruschka). In this skill, the 12 sections serve as decomposition heuristics for the Q3 branch of the Question Tree — each section becomes a sub-question. +arc42 is a 12-chapter template for documenting software architecture (Gernot Starke, Peter Hruschka). In this skill, the 12 chapters are the **fixed second level** of the Q3 branch — Q3.1 through Q3.12, in arc42 order. Every chapter is emitted as a node on every run, even when its only leaf is `[OPEN]`. Free decomposition happens only *below* these fixed nodes. ## The 12 sections as Q3 sub-questions diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/cockburn-use-cases.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/cockburn-use-cases.md index 7d4d475..fa18a68 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/cockburn-use-cases.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/cockburn-use-cases.md @@ -1,6 +1,6 @@ # Cockburn Use Cases — Decomposition Guide for Q2 (Specification) -Alistair Cockburn's *Fully Dressed* use-case format gives the Q2 branch a precise structure. Each user-goal-level use case becomes a sub-tree of Q2; the format's mandatory fields are the leaves. +Alistair Cockburn's *Fully Dressed* use-case format gives the Q2 branch a precise structure. The Q2 second level is fixed (Q2.1–Q2.6); use cases live *below* it: each user-goal-level persona use case is a sub-tree under **Q2.2** (the use-case catalog), and each system use case a sub-tree under **Q2.3** (per-interface system specs). The format's mandatory fields are the leaves. ## The fields as Q2 sub-questions @@ -25,14 +25,14 @@ Cockburn distinguishes three goal levels: - **User Goal / Sea Level** — one sitting, one user, one outcome ("place an order") - **Subfunction / Fish** — smaller actions reused by user-goal use cases ("validate address") -The Q2 branch should contain *one sub-tree per User-Goal-level use case*. Subfunctions appear inline in the Extensions or in Supplementary Specifications. Summary-level flows are usually `[OPEN]` because they describe business processes, not technical flows. +Q2.2 (the use-case catalog) should contain *one sub-tree per User-Goal-level use case*. Subfunctions appear inline in the Extensions or in Supplementary Specifications. Summary-level flows are usually `[OPEN]` because they describe business processes, not technical flows. ## System use cases vs persona use cases -Persona use cases describe user-visible behaviour. System use cases describe technical interfaces (API endpoint contracts, CLI argument grammars, event payloads, file formats). Both belong in Q2 but in separate sub-branches: +Persona use cases describe user-visible behaviour. System use cases describe technical interfaces (API endpoint contracts, CLI argument grammars, event payloads, file formats). They hang off different fixed Q2 nodes: -- `Q2.PUC.*` — persona use cases (user goal level) -- `Q2.SUC.*` — system use cases (one per technical interface) +- `Q2.2.PUC.*` — persona use cases (user goal level), under the use-case catalog +- `Q2.3.SUC.*` — system use cases (one per technical interface), under per-interface system specs System use cases are *more* code-derivable than persona use cases because the interface contract is the code. Persona use cases require domain knowledge that is often `[OPEN]`. @@ -48,7 +48,7 @@ System use cases are *more* code-derivable than persona use cases because the in A Q2 leaf is fine-grained enough when it asks about one field of one use case: -- "What is the Main Success Scenario of `Q2.PUC.PlaceOrder`?" → leaf +- "What is the Main Success Scenario of `Q2.2.PUC.PlaceOrder`?" → leaf - "What does the system do when an order is placed?" → still needs decomposition ## Reference diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.md index 5590d6c..11b8ea8 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.md @@ -4,7 +4,7 @@ Concrete examples for each major branch. Use these as templates when phrasing yo ## Q1 — Problem and Users -### Q1.1: Who is the primary user of this bounded context? +### Q1.2: Who are the primary users of this bounded context? ``` [ANSWERED] @@ -14,7 +14,7 @@ end customers. Customers themselves never interact with this bounded context directly. ``` -### Q1.3: What problem does placing-orders-on-behalf-of-customers solve? +### Q1.4: Why was this bounded context built — what problem does placing-orders-on-behalf-of-customers solve? ``` [OPEN] @@ -27,7 +27,7 @@ system that did the same? Affects how Q2 use cases should be structured. ## Q2 — Specification -### Q2.PUC.PlaceOrder.Trigger +### Q2.2.PUC.PlaceOrder.Trigger ``` [ANSWERED] @@ -37,7 +37,7 @@ JSON body { customerId, items[], shippingAddress }. Authentication is session-based via the existing Auth filter. ``` -### Q2.PUC.PlaceOrder.Postconditions +### Q2.2.PUC.PlaceOrder.Postconditions ``` [OPEN] @@ -52,7 +52,7 @@ should mention "order is queued for fulfilment" or "order is created and visible to the manager". ``` -### Q2.SUC.CreateOrderEndpoint.ErrorResponses +### Q2.3.SUC.CreateOrderEndpoint.ErrorResponses ``` [ANSWERED] @@ -164,7 +164,7 @@ Answers affect whether Q3.11 (Risks) flags absent audit logging as debt. ## Q5 — Risks and Technical Debt -### Q5.2: What test debt exists? +### Q5.1.TestDebt: What test debt exists? ``` [ANSWERED] @@ -172,10 +172,10 @@ Evidence: src/service/OrderService.java::create (66 lines, cyclomatic complexity OrderService.create has 14 branches; only the happy path plus two validation-failure paths have tests. Inventory-failure, persistence-failure, and notification-failure branches are untested. Adding tests is straightforward -once the team confirms intended behaviour for each branch (see Q2.SUC). +once the team confirms intended behaviour for each branch (see Q2.3.SUC). ``` -### Q5.4: What technical debt is the team already tracking? +### Q5.1.TrackedDebt: What technical debt is the team already tracking? ``` [OPEN] diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/iso-25010.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/iso-25010.md index 904d67a..770f893 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/iso-25010.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/iso-25010.md @@ -1,6 +1,6 @@ # ISO/IEC 25010 — Decomposition Guide for Q4 (Quality Goals) -ISO/IEC 25010 (SQuaRE Product Quality Model) defines 8 quality characteristics with sub-characteristics. In this skill they are the decomposition heuristic for the Q4 branch — each characteristic becomes a sub-question. +ISO/IEC 25010 (SQuaRE Product Quality Model) defines 8 quality characteristics with sub-characteristics. In this skill the 8 characteristics are the **fixed nodes Q4.1–Q4.8** of the Q4 branch; Q4.9 then asks which characteristic has priority. Every node is emitted on every run, even when its only leaf is `[OPEN]`. Free decomposition happens only *below* these fixed nodes. ## The 8 characteristics as Q4 sub-questions @@ -36,7 +36,7 @@ The full 25010 standard also defines a Quality-in-Use model: Effectiveness, Effi ## Quality goal *priority* is the highest-value open question -The single most useful question for the team is "which 3-5 quality characteristics are top priority, and what is the rank order?" This shapes every architecture trade-off and is the input to arc42 Q3.1 and to ADR Pugh matrices. Always include it as `[OPEN]` Q4.0 with Ask role *Architect + Product Owner*. +The single most useful question for the team is "which 3-5 quality characteristics are top priority, and what is the rank order?" This shapes every architecture trade-off and is the input to arc42 Q3.1 and to ADR Pugh matrices. This is the fixed node `Q4.9`; its leaf is almost always `[OPEN]`, with Ask role *Architect + Product Owner*. ## When to stop decomposing diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md index 96e394a..6077b10 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md @@ -12,42 +12,42 @@ Hierarchical tree, top-down. Each node has a Q-ID, the question, and (for leaves == Q1: What problem does this bounded context solve, and for whom? -=== Q1.1: Who is the primary user? +=== Q1.1: Product identity — what is this bounded context? +[ANSWERED] +Evidence: src/api/OrderController.java:18, src/service/OrderService.java::create +An order-placement context: sales staff create customer orders via a REST API. + +=== Q1.2: Who are the primary users? [ANSWERED] Evidence: src/auth/User.java:42 (role enum), src/api/OrderController.java:18 (@PreAuthorize) Sales-team users with role MANAGER place orders on behalf of customers. -=== Q1.2: What outcome does the user want? -[OPEN] -Category: business-context -Ask role: Product Owner -The code shows order creation succeeds when validation passes, but does not -reveal what success means for the user (revenue? margin? cycle time?). Need -explicit goal statement. +(Q1.3-Q1.6 omitted here for brevity — every fixed node is still emitted.) == Q2: What is the specification of this bounded context? -=== Q2.PUC.PlaceOrder: Persona use case — Place an order -==== Q2.PUC.PlaceOrder.Actor +=== Q2.2: Use-case catalog +==== Q2.2.PUC.PlaceOrder: Persona use case — Place an order +===== Q2.2.PUC.PlaceOrder.Actor [ANSWERED] Evidence: src/api/OrderController.java:18-25 Primary Actor: Sales Manager (role MANAGER) -==== Q2.PUC.PlaceOrder.Trigger +===== Q2.2.PUC.PlaceOrder.Trigger [ANSWERED] Evidence: src/api/OrderController.java:18 (POST /orders) Sales Manager submits POST /orders with order payload. -==== Q2.PUC.PlaceOrder.MainSuccess +===== Q2.2.PUC.PlaceOrder.MainSuccess [ANSWERED] Evidence: src/service/OrderService.java::create (lines 45-92) -1. System validates payload (Q2.PUC.PlaceOrder.Validation). +1. System validates payload (Q2.2.PUC.PlaceOrder.Validation). 2. System reserves inventory via InventoryClient. 3. System persists Order with status PENDING. 4. System publishes OrderCreated event. 5. System returns 201 Created with order id. -==== Q2.PUC.PlaceOrder.Postconditions +===== Q2.2.PUC.PlaceOrder.Postconditions [OPEN] Category: business-context Ask role: Product Owner, Domain Expert @@ -55,18 +55,18 @@ Code persists status=PENDING but never transitions it. Is PENDING a final state for this bounded context, or is downstream fulfilment expected to move it forward? Affects what counts as success. -(...continues for Q3, Q4, Q5...) +(...continues for the remaining fixed nodes — Q2.x, Q3, Q4, Q5...) ``` ### Q-ID scheme -- `Q1`, `Q2`, ... — the five top-level questions -- `Q1.1`, `Q1.2`, ... — direct decompositions -- `Q3.5.2` — arbitrary depth +- `Q1`, `Q2`, ... — the five root questions +- `Q1.1` ... `Q5.5` — the **fixed second level**: the same enumerated node set on every run (Q1.1–Q1.6, Q2.1–Q2.6, Q3.1–Q3.12, Q4.1–Q4.9, Q5.1–Q5.5). A given Q-ID always means the same node — `Q3.7` is always the Deployment View — so trees from different runs diff node-by-node. Emit every fixed node even when its only leaf is `[OPEN]` or `[ANSWERED: not applicable]`. +- `Q3.5.2` — arbitrary depth *below* the fixed second level; third-level depth is free, code-driven, and varies between runs. - Within named sub-trees, use a stable label between dots so cites are stable across reruns: - - `Q2.PUC.PlaceOrder.Trigger` — persona use case PlaceOrder, field Trigger - - `Q2.SUC.CreateOrderEndpoint.ErrorResponses` — system use case for the create endpoint, ErrorResponses field - - `Q3.9.HexagonalArchitecture.Context` — ADR HexagonalArchitecture, Context field + - `Q2.2.PUC.PlaceOrder.Trigger` — persona use case PlaceOrder (under Q2.2, the use-case catalog), field Trigger + - `Q2.3.SUC.CreateOrderEndpoint.ErrorResponses` — system use case (under Q2.3, per-interface system specs) for the create endpoint, ErrorResponses field + - `Q3.9.HexagonalArchitecture.Context` — ADR HexagonalArchitecture (under Q3.9, the arc42 Architecture Decisions chapter), Context field ### `[ANSWERED]` block format @@ -113,7 +113,7 @@ reveal what success means for the user (revenue? margin? cycle time?). *Your answer:* _(write here)_ -=== Q2.PUC.PlaceOrder.Postconditions +=== Q2.2.PUC.PlaceOrder.Postconditions Category: business-context Code persists status=PENDING but never transitions it. Is PENDING a final @@ -141,7 +141,7 @@ _(write here)_ ## Phase 2 traceability -The synthesized documentation must be self-contained. The Question Tree is temporary scaffolding — it is renumbered on every re-run — so its Q-IDs are NOT carried into the final documents. During Phase 2, every claim is traced back to a leaf as a build-time check; what gets *written* is the durable reference only: +The synthesized documentation must be self-contained. The Question Tree is a temporary intermediate artifact: its fixed second level (Q1.1–Q5.5) is stable, but third-level Q-IDs are run-specific, and the tree itself is not shipped alongside the docs. So Q-IDs are NOT carried into the final documents. During Phase 2, every claim is traced back to a leaf as a build-time check; what gets *written* is the durable reference only: ``` The system uses Hexagonal Architecture [src/app/Ports.java, diff --git a/skill/socratic-code-theory-recovery/SKILL.md b/skill/socratic-code-theory-recovery/SKILL.md index c1ef585..9abd8fb 100644 --- a/skill/socratic-code-theory-recovery/SKILL.md +++ b/skill/socratic-code-theory-recovery/SKILL.md @@ -71,19 +71,22 @@ The fix: model the gaps explicitly. Every question about the system is either `[ ### Phase 1: Build the Question Tree -Use [prompts/phase-1-question-tree.md](prompts/phase-1-question-tree.md). Adapt the bounded-context path and any domain-specific Q1 examples; do not change the leaf classification, Q-ID scheme, or output files. +Use [prompts/phase-1-question-tree.md](prompts/phase-1-question-tree.md). Adapt the bounded-context path and the Q1-Q5 wording; do not change the fixed second level, the leaf classification, the Q-ID scheme, or the output files. Outputs: - `QUESTION_TREE.adoc` — the full hierarchical reasoning trace - `OPEN_QUESTIONS.adoc` — only the `[OPEN]` leaves, grouped by Ask role -Decomposition heuristics — use these Semantic Anchors as guides, not as rigid templates: +The five root questions decompose into a **fixed second level** — the same enumerated node set on every run, so Q-IDs are stable and trees from different runs can be diffed node-by-node. Free, code-driven decomposition applies only *below* the fixed level. The fixed nodes: -- **arc42** — 12 architecture sub-questions (Q3 branch). See [references/arc42.md](references/arc42.md). -- **Cockburn Use Cases** — specification structure (Q2 branch). See [references/cockburn-use-cases.md](references/cockburn-use-cases.md). -- **ISO/IEC 25010** — 8 quality characteristics (Q4 branch). See [references/iso-25010.md](references/iso-25010.md). -- **Nygard ADRs** — design-rationale capture (Q3.9 branch). See [references/nygard-adrs.md](references/nygard-adrs.md). +- **Q1.1–Q1.6** — product identity, primary users, channels, why-built, success metrics, segment priority. +- **Q2.1–Q2.6** — actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules. See [references/cockburn-use-cases.md](references/cockburn-use-cases.md). +- **Q3.1–Q3.12** — the twelve arc42 chapters, in arc42 order. See [references/arc42.md](references/arc42.md). Design rationale lives in the Q3.9 chapter — see [references/nygard-adrs.md](references/nygard-adrs.md). +- **Q4.1–Q4.8** — the eight ISO/IEC 25010 characteristics; **Q4.9** — which characteristic has priority. See [references/iso-25010.md](references/iso-25010.md). +- **Q5.1–Q5.5** — technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks. + +Every fixed node is emitted even when its only leaf is `[OPEN]` or `[ANSWERED: not applicable]`. Leaf classification rules and Q-ID scheme: [references/output-schema.md](references/output-schema.md). diff --git a/skill/socratic-code-theory-recovery/prompts/phase-1-question-tree.md b/skill/socratic-code-theory-recovery/prompts/phase-1-question-tree.md index 4229c25..6059df7 100644 --- a/skill/socratic-code-theory-recovery/prompts/phase-1-question-tree.md +++ b/skill/socratic-code-theory-recovery/prompts/phase-1-question-tree.md @@ -1,6 +1,6 @@ # Phase 1 Prompt: Build the Question Tree -Copy the block below into a session that has read access to the bounded context. Replace `[bounded context path]` with the actual path. Adapt the Q1-Q5 examples if your domain has different starting concerns, but do not change the leaf classification, Q-ID scheme, or output files. +Copy the block below into a session that has read access to the bounded context. Replace `[bounded context path]` with the actual path. Adapt the Q1-Q5 wording if your domain has different starting concerns, but do not change the fixed second level, the leaf classification, the Q-ID scheme, or the output files. ``` You are performing Socratic Code-Theory Recovery on a brownfield bounded @@ -11,26 +11,34 @@ recursive question refinement, before any documentation is written. Process: -1. Start with five high-level questions about the bounded context: +1. Start with five root questions about the bounded context: Q1 What problem does this bounded context solve, and for whom? Q2 What is the specification of this bounded context? Q3 What is the architecture of this bounded context? Q4 What quality goals drive the design? Q5 What risks and technical debt exist? -2. Decompose each question recursively. Use these Semantic Anchors as - decomposition guides: - - arc42 — 12 sub-questions for architecture (Q3 branch) - - Cockburn Use Cases — Primary Actor, Trigger, Main Success Scenario, - Extensions, Postconditions for specification (Q2 branch) - - ISO/IEC 25010 — 8 quality characteristics for quality goals (Q4 branch) - - Nygard ADRs — Context, Decision, Status, Consequences for design - rationale (Q3.9 branch) - Stop decomposing when a question is precise enough to be answered with a - single piece of code evidence or a single fact from a stakeholder. - -3. Assign a hierarchical Q-ID to every node (Q1, Q1.2, Q1.2.3, ...) so that - later documentation can cite back to it. +2. The second level of the tree is FIXED, not free. Emit exactly these + nodes, in this order, even when a node's only leaf is [OPEN] or + [ANSWERED: not applicable]: + Q1.1-Q1.6 product identity, primary users, channels, why-built, + success metrics, segment priority + Q2.1-Q2.6 actors, use-case catalog, per-interface system specs, + data/entity model, acceptance criteria, cross-cutting + business rules + Q3.1-Q3.12 the twelve arc42 chapters, in arc42 order + Q4.1-Q4.8 the eight ISO/IEC 25010 characteristics; + Q4.9 which characteristic has priority + Q5.1-Q5.5 technical debt, security risks, operational risks, + dependency/supply-chain risks, scaling/performance risks + +3. Below the fixed second level, decompose freely and code-driven. Stop + when a leaf is small enough to answer from a single piece of code + evidence, or to pose as a single precise question to a stakeholder. + Third-level depth varies between runs + — that is expected. Q-IDs are stable: Q3.7 is always the Deployment + View, in every run, so trees from different runs can be diffed + node-by-node. 4. For each leaf, classify it: @@ -57,7 +65,9 @@ Process: OPEN_QUESTIONS.adoc - Only the [OPEN] leaves, copied verbatim from QUESTION_TREE.adoc - - Grouped by Ask role (one section per role) + - Always one section per Ask role (Product Owner, Architect, + Developer, Domain Expert, Operations) — emit every section even + when it is empty ("No open questions for this role") - Each question short enough to be answered in 1-3 sentences Do not write any other documentation in this phase. Phase 2 will synthesize diff --git a/skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md b/skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md index a8370a9..14e49dc 100644 --- a/skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md +++ b/skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md @@ -51,9 +51,10 @@ Produce four artifacts: Rules for traceability: - The synthesized documentation must be self-contained. The Question Tree - is temporary scaffolding — it is renumbered on every re-run — so Q-IDs - must NOT appear in the output. While synthesizing, trace every claim - back to a leaf: each claim must come from an [ANSWERED] leaf or an + is a temporary intermediate artifact — its fixed second level is stable, + but third-level Q-IDs are run-specific and the tree is not shipped — so + Q-IDs must NOT appear in the output. While synthesizing, trace every + claim back to a leaf: each claim must come from an [ANSWERED] leaf or an answered [OPEN] leaf. This tracing is a build-time check, not something written into the documents. - A claim backed by an [ANSWERED] leaf cites the code evidence from that diff --git a/skill/socratic-code-theory-recovery/references/arc42.md b/skill/socratic-code-theory-recovery/references/arc42.md index b925422..8bfa5c4 100644 --- a/skill/socratic-code-theory-recovery/references/arc42.md +++ b/skill/socratic-code-theory-recovery/references/arc42.md @@ -1,6 +1,6 @@ # arc42 — Decomposition Guide for Q3 (Architecture) -arc42 is a 12-section template for documenting software architecture (Gernot Starke, Peter Hruschka). In this skill, the 12 sections serve as decomposition heuristics for the Q3 branch of the Question Tree — each section becomes a sub-question. +arc42 is a 12-chapter template for documenting software architecture (Gernot Starke, Peter Hruschka). In this skill, the 12 chapters are the **fixed second level** of the Q3 branch — Q3.1 through Q3.12, in arc42 order. Every chapter is emitted as a node on every run, even when its only leaf is `[OPEN]`. Free decomposition happens only *below* these fixed nodes. ## The 12 sections as Q3 sub-questions diff --git a/skill/socratic-code-theory-recovery/references/cockburn-use-cases.md b/skill/socratic-code-theory-recovery/references/cockburn-use-cases.md index 7d4d475..fa18a68 100644 --- a/skill/socratic-code-theory-recovery/references/cockburn-use-cases.md +++ b/skill/socratic-code-theory-recovery/references/cockburn-use-cases.md @@ -1,6 +1,6 @@ # Cockburn Use Cases — Decomposition Guide for Q2 (Specification) -Alistair Cockburn's *Fully Dressed* use-case format gives the Q2 branch a precise structure. Each user-goal-level use case becomes a sub-tree of Q2; the format's mandatory fields are the leaves. +Alistair Cockburn's *Fully Dressed* use-case format gives the Q2 branch a precise structure. The Q2 second level is fixed (Q2.1–Q2.6); use cases live *below* it: each user-goal-level persona use case is a sub-tree under **Q2.2** (the use-case catalog), and each system use case a sub-tree under **Q2.3** (per-interface system specs). The format's mandatory fields are the leaves. ## The fields as Q2 sub-questions @@ -25,14 +25,14 @@ Cockburn distinguishes three goal levels: - **User Goal / Sea Level** — one sitting, one user, one outcome ("place an order") - **Subfunction / Fish** — smaller actions reused by user-goal use cases ("validate address") -The Q2 branch should contain *one sub-tree per User-Goal-level use case*. Subfunctions appear inline in the Extensions or in Supplementary Specifications. Summary-level flows are usually `[OPEN]` because they describe business processes, not technical flows. +Q2.2 (the use-case catalog) should contain *one sub-tree per User-Goal-level use case*. Subfunctions appear inline in the Extensions or in Supplementary Specifications. Summary-level flows are usually `[OPEN]` because they describe business processes, not technical flows. ## System use cases vs persona use cases -Persona use cases describe user-visible behaviour. System use cases describe technical interfaces (API endpoint contracts, CLI argument grammars, event payloads, file formats). Both belong in Q2 but in separate sub-branches: +Persona use cases describe user-visible behaviour. System use cases describe technical interfaces (API endpoint contracts, CLI argument grammars, event payloads, file formats). They hang off different fixed Q2 nodes: -- `Q2.PUC.*` — persona use cases (user goal level) -- `Q2.SUC.*` — system use cases (one per technical interface) +- `Q2.2.PUC.*` — persona use cases (user goal level), under the use-case catalog +- `Q2.3.SUC.*` — system use cases (one per technical interface), under per-interface system specs System use cases are *more* code-derivable than persona use cases because the interface contract is the code. Persona use cases require domain knowledge that is often `[OPEN]`. @@ -48,7 +48,7 @@ System use cases are *more* code-derivable than persona use cases because the in A Q2 leaf is fine-grained enough when it asks about one field of one use case: -- "What is the Main Success Scenario of `Q2.PUC.PlaceOrder`?" → leaf +- "What is the Main Success Scenario of `Q2.2.PUC.PlaceOrder`?" → leaf - "What does the system do when an order is placed?" → still needs decomposition ## Reference diff --git a/skill/socratic-code-theory-recovery/references/examples.md b/skill/socratic-code-theory-recovery/references/examples.md index 5590d6c..11b8ea8 100644 --- a/skill/socratic-code-theory-recovery/references/examples.md +++ b/skill/socratic-code-theory-recovery/references/examples.md @@ -4,7 +4,7 @@ Concrete examples for each major branch. Use these as templates when phrasing yo ## Q1 — Problem and Users -### Q1.1: Who is the primary user of this bounded context? +### Q1.2: Who are the primary users of this bounded context? ``` [ANSWERED] @@ -14,7 +14,7 @@ end customers. Customers themselves never interact with this bounded context directly. ``` -### Q1.3: What problem does placing-orders-on-behalf-of-customers solve? +### Q1.4: Why was this bounded context built — what problem does placing-orders-on-behalf-of-customers solve? ``` [OPEN] @@ -27,7 +27,7 @@ system that did the same? Affects how Q2 use cases should be structured. ## Q2 — Specification -### Q2.PUC.PlaceOrder.Trigger +### Q2.2.PUC.PlaceOrder.Trigger ``` [ANSWERED] @@ -37,7 +37,7 @@ JSON body { customerId, items[], shippingAddress }. Authentication is session-based via the existing Auth filter. ``` -### Q2.PUC.PlaceOrder.Postconditions +### Q2.2.PUC.PlaceOrder.Postconditions ``` [OPEN] @@ -52,7 +52,7 @@ should mention "order is queued for fulfilment" or "order is created and visible to the manager". ``` -### Q2.SUC.CreateOrderEndpoint.ErrorResponses +### Q2.3.SUC.CreateOrderEndpoint.ErrorResponses ``` [ANSWERED] @@ -164,7 +164,7 @@ Answers affect whether Q3.11 (Risks) flags absent audit logging as debt. ## Q5 — Risks and Technical Debt -### Q5.2: What test debt exists? +### Q5.1.TestDebt: What test debt exists? ``` [ANSWERED] @@ -172,10 +172,10 @@ Evidence: src/service/OrderService.java::create (66 lines, cyclomatic complexity OrderService.create has 14 branches; only the happy path plus two validation-failure paths have tests. Inventory-failure, persistence-failure, and notification-failure branches are untested. Adding tests is straightforward -once the team confirms intended behaviour for each branch (see Q2.SUC). +once the team confirms intended behaviour for each branch (see Q2.3.SUC). ``` -### Q5.4: What technical debt is the team already tracking? +### Q5.1.TrackedDebt: What technical debt is the team already tracking? ``` [OPEN] diff --git a/skill/socratic-code-theory-recovery/references/iso-25010.md b/skill/socratic-code-theory-recovery/references/iso-25010.md index 904d67a..770f893 100644 --- a/skill/socratic-code-theory-recovery/references/iso-25010.md +++ b/skill/socratic-code-theory-recovery/references/iso-25010.md @@ -1,6 +1,6 @@ # ISO/IEC 25010 — Decomposition Guide for Q4 (Quality Goals) -ISO/IEC 25010 (SQuaRE Product Quality Model) defines 8 quality characteristics with sub-characteristics. In this skill they are the decomposition heuristic for the Q4 branch — each characteristic becomes a sub-question. +ISO/IEC 25010 (SQuaRE Product Quality Model) defines 8 quality characteristics with sub-characteristics. In this skill the 8 characteristics are the **fixed nodes Q4.1–Q4.8** of the Q4 branch; Q4.9 then asks which characteristic has priority. Every node is emitted on every run, even when its only leaf is `[OPEN]`. Free decomposition happens only *below* these fixed nodes. ## The 8 characteristics as Q4 sub-questions @@ -36,7 +36,7 @@ The full 25010 standard also defines a Quality-in-Use model: Effectiveness, Effi ## Quality goal *priority* is the highest-value open question -The single most useful question for the team is "which 3-5 quality characteristics are top priority, and what is the rank order?" This shapes every architecture trade-off and is the input to arc42 Q3.1 and to ADR Pugh matrices. Always include it as `[OPEN]` Q4.0 with Ask role *Architect + Product Owner*. +The single most useful question for the team is "which 3-5 quality characteristics are top priority, and what is the rank order?" This shapes every architecture trade-off and is the input to arc42 Q3.1 and to ADR Pugh matrices. This is the fixed node `Q4.9`; its leaf is almost always `[OPEN]`, with Ask role *Architect + Product Owner*. ## When to stop decomposing diff --git a/skill/socratic-code-theory-recovery/references/output-schema.md b/skill/socratic-code-theory-recovery/references/output-schema.md index 96e394a..6077b10 100644 --- a/skill/socratic-code-theory-recovery/references/output-schema.md +++ b/skill/socratic-code-theory-recovery/references/output-schema.md @@ -12,42 +12,42 @@ Hierarchical tree, top-down. Each node has a Q-ID, the question, and (for leaves == Q1: What problem does this bounded context solve, and for whom? -=== Q1.1: Who is the primary user? +=== Q1.1: Product identity — what is this bounded context? +[ANSWERED] +Evidence: src/api/OrderController.java:18, src/service/OrderService.java::create +An order-placement context: sales staff create customer orders via a REST API. + +=== Q1.2: Who are the primary users? [ANSWERED] Evidence: src/auth/User.java:42 (role enum), src/api/OrderController.java:18 (@PreAuthorize) Sales-team users with role MANAGER place orders on behalf of customers. -=== Q1.2: What outcome does the user want? -[OPEN] -Category: business-context -Ask role: Product Owner -The code shows order creation succeeds when validation passes, but does not -reveal what success means for the user (revenue? margin? cycle time?). Need -explicit goal statement. +(Q1.3-Q1.6 omitted here for brevity — every fixed node is still emitted.) == Q2: What is the specification of this bounded context? -=== Q2.PUC.PlaceOrder: Persona use case — Place an order -==== Q2.PUC.PlaceOrder.Actor +=== Q2.2: Use-case catalog +==== Q2.2.PUC.PlaceOrder: Persona use case — Place an order +===== Q2.2.PUC.PlaceOrder.Actor [ANSWERED] Evidence: src/api/OrderController.java:18-25 Primary Actor: Sales Manager (role MANAGER) -==== Q2.PUC.PlaceOrder.Trigger +===== Q2.2.PUC.PlaceOrder.Trigger [ANSWERED] Evidence: src/api/OrderController.java:18 (POST /orders) Sales Manager submits POST /orders with order payload. -==== Q2.PUC.PlaceOrder.MainSuccess +===== Q2.2.PUC.PlaceOrder.MainSuccess [ANSWERED] Evidence: src/service/OrderService.java::create (lines 45-92) -1. System validates payload (Q2.PUC.PlaceOrder.Validation). +1. System validates payload (Q2.2.PUC.PlaceOrder.Validation). 2. System reserves inventory via InventoryClient. 3. System persists Order with status PENDING. 4. System publishes OrderCreated event. 5. System returns 201 Created with order id. -==== Q2.PUC.PlaceOrder.Postconditions +===== Q2.2.PUC.PlaceOrder.Postconditions [OPEN] Category: business-context Ask role: Product Owner, Domain Expert @@ -55,18 +55,18 @@ Code persists status=PENDING but never transitions it. Is PENDING a final state for this bounded context, or is downstream fulfilment expected to move it forward? Affects what counts as success. -(...continues for Q3, Q4, Q5...) +(...continues for the remaining fixed nodes — Q2.x, Q3, Q4, Q5...) ``` ### Q-ID scheme -- `Q1`, `Q2`, ... — the five top-level questions -- `Q1.1`, `Q1.2`, ... — direct decompositions -- `Q3.5.2` — arbitrary depth +- `Q1`, `Q2`, ... — the five root questions +- `Q1.1` ... `Q5.5` — the **fixed second level**: the same enumerated node set on every run (Q1.1–Q1.6, Q2.1–Q2.6, Q3.1–Q3.12, Q4.1–Q4.9, Q5.1–Q5.5). A given Q-ID always means the same node — `Q3.7` is always the Deployment View — so trees from different runs diff node-by-node. Emit every fixed node even when its only leaf is `[OPEN]` or `[ANSWERED: not applicable]`. +- `Q3.5.2` — arbitrary depth *below* the fixed second level; third-level depth is free, code-driven, and varies between runs. - Within named sub-trees, use a stable label between dots so cites are stable across reruns: - - `Q2.PUC.PlaceOrder.Trigger` — persona use case PlaceOrder, field Trigger - - `Q2.SUC.CreateOrderEndpoint.ErrorResponses` — system use case for the create endpoint, ErrorResponses field - - `Q3.9.HexagonalArchitecture.Context` — ADR HexagonalArchitecture, Context field + - `Q2.2.PUC.PlaceOrder.Trigger` — persona use case PlaceOrder (under Q2.2, the use-case catalog), field Trigger + - `Q2.3.SUC.CreateOrderEndpoint.ErrorResponses` — system use case (under Q2.3, per-interface system specs) for the create endpoint, ErrorResponses field + - `Q3.9.HexagonalArchitecture.Context` — ADR HexagonalArchitecture (under Q3.9, the arc42 Architecture Decisions chapter), Context field ### `[ANSWERED]` block format @@ -113,7 +113,7 @@ reveal what success means for the user (revenue? margin? cycle time?). *Your answer:* _(write here)_ -=== Q2.PUC.PlaceOrder.Postconditions +=== Q2.2.PUC.PlaceOrder.Postconditions Category: business-context Code persists status=PENDING but never transitions it. Is PENDING a final @@ -141,7 +141,7 @@ _(write here)_ ## Phase 2 traceability -The synthesized documentation must be self-contained. The Question Tree is temporary scaffolding — it is renumbered on every re-run — so its Q-IDs are NOT carried into the final documents. During Phase 2, every claim is traced back to a leaf as a build-time check; what gets *written* is the durable reference only: +The synthesized documentation must be self-contained. The Question Tree is a temporary intermediate artifact: its fixed second level (Q1.1–Q5.5) is stable, but third-level Q-IDs are run-specific, and the tree itself is not shipped alongside the docs. So Q-IDs are NOT carried into the final documents. During Phase 2, every claim is traced back to a leaf as a build-time check; what gets *written* is the durable reference only: ``` The system uses Hexagonal Architecture [src/app/Ports.java, diff --git a/website/public/data/contracts.json b/website/public/data/contracts.json index a9b9a9b..bdfd3c8 100644 --- a/website/public/data/contracts.json +++ b/website/public/data/contracts.json @@ -155,8 +155,8 @@ "adr-according-to-nygard", "mental-model-according-to-naur" ], - "template": "Recover a program's \"theory\" (Naur 1985) from source code through recursive question refinement.\n- Start with 5 high-level questions: Problem/Users, Specification, Architecture, Quality Goals, Risks\n- Decompose each question using Semantic Anchors as guides: arc42 (12 sub-questions), Cockburn Use Cases, ISO 25010, Nygard ADRs\n- Each leaf is either `[ANSWERED]` (with code evidence) or `[OPEN]` (with Category, Ask role, and why unanswerable)\n- The Question Tree is the primary artifact; documentation is synthesized from answered leaves\n- Open Questions are the handoff document: routed by role (Product Owner, Architect, Developer, Domain Expert, Operations)\n- Two-phase workflow: Phase 1 builds the tree, team answers Open Questions, Phase 2 produces documentation with Q-ID traceability", - "templateDe": "Die \"Theorie\" eines Programms (Naur 1985) aus dem Quellcode durch rekursive Fragenverfeinerung rekonstruieren.\n- Start mit 5 High-Level-Fragen: Problem/Nutzer, Spezifikation, Architektur, Qualitätsziele, Risiken\n- Jede Frage mit Semantic Anchors als Leitfaden zerlegen: arc42 (12 Unterfragen), Cockburn Use Cases, ISO 25010, Nygard ADRs\n- Jedes Blatt ist entweder `[BEANTWORTET]` (mit Code-Evidenz) oder `[OFFEN]` (mit Kategorie, zuständiger Rolle und Begründung warum nicht beantwortbar)\n- Der Fragenbaum ist das primäre Artefakt; Dokumentation wird aus beantworteten Blättern synthetisiert\n- Offene Fragen sind das Übergabedokument: nach Rolle geroutet (Product Owner, Architekt, Entwickler, Domänenexperte, Operations)\n- Zwei-Phasen-Workflow: Phase 1 baut den Baum, Team beantwortet offene Fragen, Phase 2 erzeugt Dokumentation mit Q-ID-Rückverfolgbarkeit", + "template": "Recover a program's \"theory\" (Naur 1985) from source code through recursive question refinement.\n\n- Start with 5 root questions: Q1 Problem/Users, Q2 Specification, Q3 Architecture, Q4 Quality Goals, Q5 Risks.\n\n- The second level of the tree is FIXED, not free. Every run emits exactly these nodes, in this order, even when a node's only leaf is [OPEN] or [ANSWERED: not applicable]:\n - Q1.1-Q1.6: product identity, primary users, channels, why-built, success metrics, segment priority\n - Q2.1-Q2.6: actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules\n - Q3.1-Q3.12: the twelve arc42 chapters, in arc42 order\n - Q4.1-Q4.8: the eight ISO/IEC 25010 characteristics; plus Q4.9: which characteristic has priority\n - Q5.1-Q5.5: technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks\n\n- Below the fixed second level, decompose freely and code-driven; stop when a leaf is small enough to answer from one piece of code evidence, or to pose as one precise stakeholder question. Third-level depth varies between runs — expected.\n\n- Q-IDs are stable: Q3.7 is always Deployment View, in every run, so trees from different runs can be diffed node-by-node.\n\n- Each leaf is [ANSWERED] (with file:line evidence) or [OPEN] (with Category, Ask role, and why it is unanswerable from code).\n\n- Open Questions are the handoff document: always emit one section per role (Product Owner, Architect, Developer, Domain Expert, Operations), even when a section is empty (\"No open questions for this role\").\n\n- Two-phase workflow: Phase 1 builds the tree; the team answers the Open Questions; Phase 2 synthesizes documentation from the answered tree.", + "templateDe": "Die \"Theorie\" eines Programms (Naur 1985) aus dem Quellcode durch rekursive Fragenverfeinerung rekonstruieren.\n\n- Mit 5 Wurzelfragen starten: Q1 Problem/Nutzer, Q2 Spezifikation, Q3 Architektur, Q4 Qualitätsziele, Q5 Risiken.\n\n- Die zweite Baumebene ist FIX, nicht frei. Jeder Lauf erzeugt genau diese Knoten, in dieser Reihenfolge, auch wenn ein Knoten nur ein [OPEN]- oder [ANSWERED: not applicable]-Blatt hat:\n - Q1.1-Q1.6: Produktidentität, primäre Nutzer, Kanäle, Warum-gebaut, Erfolgsmetriken, Segmentpriorität\n - Q2.1-Q2.6: Akteure, Use-Case-Katalog, System-Specs pro Schnittstelle, Daten-/Entity-Modell, Akzeptanzkriterien, übergreifende Geschäftsregeln\n - Q3.1-Q3.12: die zwölf arc42-Kapitel, in arc42-Reihenfolge\n - Q4.1-Q4.8: die acht ISO/IEC-25010-Merkmale; plus Q4.9: welches Merkmal Priorität hat\n - Q5.1-Q5.5: technische Schuld, Sicherheitsrisiken, Betriebsrisiken, Abhängigkeits-/Supply-Chain-Risiken, Skalierungs-/Performance-Risiken\n\n- Unterhalb der fixen zweiten Ebene frei und code-getrieben zerlegen; stoppen, wenn ein Blatt aus einem Stück Code-Evidenz oder einem Stakeholder-Fakt beantwortbar ist. Die Tiefe der dritten Ebene variiert zwischen Läufen — erwartet.\n\n- Q-IDs sind stabil: Q3.7 ist in jedem Lauf die Verteilungssicht, sodass Bäume verschiedener Läufe Knoten für Knoten verglichen werden können.\n\n- Jedes Blatt ist [ANSWERED] (mit file:line-Evidenz) oder [OPEN] (mit Kategorie, zuständiger Rolle und Begründung, warum es aus dem Code nicht beantwortbar ist).\n\n- Offene Fragen sind das Übergabedokument: immer einen Abschnitt pro Rolle erzeugen (Product Owner, Architekt, Entwickler, Domänenexperte, Operations), auch wenn ein Abschnitt leer ist (\"Keine offenen Fragen für diese Rolle\").\n\n- Zwei-Phasen-Workflow: Phase 1 baut den Baum; das Team beantwortet die offenen Fragen; Phase 2 synthetisiert Dokumentation aus dem beantworteten Baum.", "category": "documentation" }, { diff --git a/website/public/llms.txt b/website/public/llms.txt index f940d2f..1f4b6a9 100644 --- a/website/public/llms.txt +++ b/website/public/llms.txt @@ -6369,12 +6369,25 @@ Documentation follows Docs-as-Code according to Ralf D. Müller: ## Socratic Code Theory Recovery Recover a program's "theory" (Naur 1985) from source code through recursive question refinement. -- Start with 5 high-level questions: Problem/Users, Specification, Architecture, Quality Goals, Risks -- Decompose each question using Semantic Anchors as guides: arc42 (12 sub-questions), Cockburn Use Cases, ISO 25010, Nygard ADRs -- Each leaf is either `[ANSWERED]` (with code evidence) or `[OPEN]` (with Category, Ask role, and why unanswerable) -- The Question Tree is the primary artifact; documentation is synthesized from answered leaves -- Open Questions are the handoff document: routed by role (Product Owner, Architect, Developer, Domain Expert, Operations) -- Two-phase workflow: Phase 1 builds the tree, team answers Open Questions, Phase 2 produces documentation with Q-ID traceability + +- Start with 5 root questions: Q1 Problem/Users, Q2 Specification, Q3 Architecture, Q4 Quality Goals, Q5 Risks. + +- The second level of the tree is FIXED, not free. Every run emits exactly these nodes, in this order, even when a node's only leaf is [OPEN] or [ANSWERED: not applicable]: + - Q1.1-Q1.6: product identity, primary users, channels, why-built, success metrics, segment priority + - Q2.1-Q2.6: actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules + - Q3.1-Q3.12: the twelve arc42 chapters, in arc42 order + - Q4.1-Q4.8: the eight ISO/IEC 25010 characteristics; plus Q4.9: which characteristic has priority + - Q5.1-Q5.5: technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks + +- Below the fixed second level, decompose freely and code-driven; stop when a leaf is small enough to answer from one piece of code evidence, or to pose as one precise stakeholder question. Third-level depth varies between runs — expected. + +- Q-IDs are stable: Q3.7 is always Deployment View, in every run, so trees from different runs can be diffed node-by-node. + +- Each leaf is [ANSWERED] (with file:line evidence) or [OPEN] (with Category, Ask role, and why it is unanswerable from code). + +- Open Questions are the handoff document: always emit one section per role (Product Owner, Architect, Developer, Domain Expert, Operations), even when a section is empty ("No open questions for this role"). + +- Two-phase workflow: Phase 1 builds the tree; the team answers the Open Questions; Phase 2 synthesizes documentation from the answered tree. *Referenced anchors: socratic-method, arc42, iso-25010, adr-according-to-nygard, mental-model-according-to-naur*