diff --git a/docs/socratic-recovery-skill.adoc b/docs/socratic-recovery-skill.adoc index 892f4b7..7700d23 100644 --- a/docs/socratic-recovery-skill.adoc +++ b/docs/socratic-recovery-skill.adoc @@ -44,7 +44,19 @@ The skill follows the https://agentskills.io[agentskills.io] specification. Refe === link:https://docs.anthropic.com/en/docs/claude-code/memory[Claude Code] -Reference the skill directly in `CLAUDE.md`: +**Recommended: install via the Claude Code Plugin Marketplace.** This repository is published as a Claude Code marketplace; the plugin bundles all Semantic Anchors skills (Translator, Onboarding, and Socratic Code-Theory Recovery) in one install. + +Run inside any Claude Code session: + +[source,text] +---- +/plugin marketplace add LLM-Coding/Semantic-Anchors +/plugin install semantic-anchors@semantic-anchors +---- + +The skills become available immediately — Claude Code picks up the `socratic-code-theory-recovery` skill from the installed plugin without any further edits to `CLAUDE.md`. + +**Alternative: reference the skill manually in `CLAUDE.md`** when you cannot or do not want to use the marketplace flow (corporate Claude installs, pinned versions, custom skill locations): [source,markdown] ---- @@ -61,8 +73,6 @@ Phase 2 prompt: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md ---- -Or place the `skill/socratic-code-theory-recovery/SKILL.md` in your project's skills directory if your Claude Code setup uses a custom skills location. - === link:https://openai.com/codex/[Codex] Codex supports `AGENTS.md` for repository instructions: diff --git a/docs/socratic-recovery-skill.de.adoc b/docs/socratic-recovery-skill.de.adoc index 6625ad3..3adb01f 100644 --- a/docs/socratic-recovery-skill.de.adoc +++ b/docs/socratic-recovery-skill.de.adoc @@ -44,7 +44,19 @@ Der Skill folgt der https://agentskills.io[agentskills.io]-Spezifikation. Verwei === link:https://docs.anthropic.com/en/docs/claude-code/memory[Claude Code] -Skill in `CLAUDE.md` referenzieren: +**Empfohlen: Installation über den Claude-Code-Plugin-Marketplace.** Dieses Repository ist als Claude-Code-Marketplace veröffentlicht; das Plugin bündelt alle Semantic-Anchors-Skills (Translator, Onboarding, Socratic Code-Theory Recovery) in einer Installation. + +In einer Claude-Code-Session ausführen: + +[source,text] +---- +/plugin marketplace add LLM-Coding/Semantic-Anchors +/plugin install semantic-anchors@semantic-anchors +---- + +Die Skills sind sofort verfügbar — Claude Code erkennt den `socratic-code-theory-recovery`-Skill aus dem installierten Plugin, ohne dass `CLAUDE.md` angepasst werden muss. + +**Alternative: Skill manuell in `CLAUDE.md` referenzieren**, wenn der Marketplace-Weg nicht passt (Corporate-Installationen, gepinnte Versionen, eigene Skill-Verzeichnisse): [source,markdown] ---- @@ -61,8 +73,6 @@ Phase 2 prompt: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md ---- -Alternativ kann `skill/socratic-code-theory-recovery/SKILL.md` ins Skills-Verzeichnis deines Projekts gelegt werden, wenn die Claude-Code-Konfiguration einen eigenen Skills-Pfad nutzt. - === link:https://openai.com/codex/[Codex] Codex unterstützt `AGENTS.md` für Repo-Anweisungen: diff --git a/plugins/semantic-anchors/skills/semantic-anchor-translator/references/catalog.md b/plugins/semantic-anchors/skills/semantic-anchor-translator/references/catalog.md index 727e392..da0286f 100644 --- a/plugins/semantic-anchors/skills/semantic-anchor-translator/references/catalog.md +++ b/plugins/semantic-anchors/skills/semantic-anchor-translator/references/catalog.md @@ -81,6 +81,11 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Percy Liang (Stanford HELM), EleutherAI (Open LLM Leaderboard), LMSYS (Chatbot Arena) - **Core:** Frameworks and metrics for assessing LLM capabilities — benchmark suites (MMLU, HumanEval, BIG-Bench), automatic vs. human evaluation, HELM, Chatbot Arena Elo ratings, red-teaming, contamination detection +### Red/Green TDD +- **Also known as:** Red-Green-Refactor, Classical TDD Cycle, Test-First Development +- **Proponents:** Kent Beck +- **Core:** Classical TDD cycle — write failing test first (red), minimal code to pass (green), then refactor; watch it fail for the right reason; one failing test at a time; test names describe behavior, not method signatures; counters the default LLM habit of writing tests after the implementation + ## Software Architecture ### Clean Architecture @@ -141,11 +146,26 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Stefan Toth, Stefan Zörner - **Core:** Lightweight architecture description framework — describe a system through four lenses: Layers (structural decomposition), Aspects (cross-cutting concerns), Solution Strategy (key technology and design choices), Rationale (documented reasoning behind decisions); pairs naturally with arc42 and ADRs +### Lehman's Software Classification +- **Also known as:** SPE Classification, Lehman's SPE Taxonomy +- **Proponents:** Meir M. Lehman +- **Core:** Three software types by relationship to reality — S-type (formally specifiable, provable), P-type (real problem, only approximable, validate against reality), E-type (embedded in the world, changes the world through use, requirements drift by nature); basis for Lehman's Laws of Software Evolution (Continuing Change, Increasing Complexity, etc.) which explain why E-type systems require ongoing maintenance + ### OWASP Top 10 - **Also known as:** OWASP Top Ten, Open Worldwide Application Security Project Top 10 - **Proponents:** OWASP Foundation - **Core:** Consensus ranking of the ten most critical web-application security risks (Broken Access Control, Cryptographic Failures, Injection, Insecure Design, Security Misconfiguration, Vulnerable Components, Authentication Failures, Data Integrity Failures, Logging Failures, SSRF); used as a baseline checklist for secure code review, threat modeling, and compliance +### Walking Skeleton +- **Also known as:** Skeleton Architecture, End-to-End Thin Implementation +- **Proponents:** Alistair Cockburn +- **Core:** Minimal end-to-end implementation touching every architectural layer (UI → logic → persistence → deployment) that is production-capable from day one; validates integration and structure before any significant feature work; grown iteratively rather than thrown away like a prototype + +### Tracer Bullet +- **Also known as:** Tracer Bullet Development, Tracer Code +- **Proponents:** Andy Hunt, David Thomas +- **Core:** Lightweight end-to-end slice that validates architectural direction on real infrastructure; unlike a spike, tracer code is kept and refined into the final system; enables rapid directional correction via the "aim-fire-adjust" loop; primary goal is architecture validation, not feature delivery + ## Design Principles ### SOLID Principles @@ -209,6 +229,16 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Ron Jeffries, Kent Beck - **Core:** Don't build for hypothetical futures, speculative generality anti-pattern, incremental design, delete dead code +### Single Level of Abstraction Principle (SLAP) +- **Also known as:** SLAP, One Level of Abstraction Per Function +- **Proponents:** Kent Beck, Robert C. Martin +- **Core:** All statements inside a function should live at one abstraction level; mixing orchestration with mechanics is the main driver of unreadable code; refactor by extracting low-level details into named helpers so the outer function reads like a table of contents; formal expression of Beck's Composed Method pattern, codified as a Clean Code function-design rule by Martin + +### Code Smells +- **Also known as:** Bad Smells in Code, Refactoring Smells +- **Proponents:** Kent Beck (coined term), Martin Fowler, Robert C. Martin +- **Core:** Surface indications in code that usually point to deeper design problems; Fowler's *Refactoring* (1999) catalogue groups ~20 smells into Bloaters (Long Method, Large Class, Primitive Obsession), OO Abusers (Switch Statements, Refused Bequest), Change Preventers (Divergent Change, Shotgun Surgery), Dispensables (Duplicate Code, Dead Code, Speculative Generality), Couplers (Feature Envy, Message Chains); Martin's *Clean Code* Appendix A extends with ~65 heuristics across Comments, Functions, Names, Tests; each smell pairs with a canonical refactoring — a smell tells you *where to look*, not *what to do* + ### GoF Design Patterns - **Also known as:** Design Patterns, Gang of Four Patterns - **Proponents:** Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides @@ -332,6 +362,16 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors ### Devil's Advocate - **Core:** Argue against proposal to stress-test it +### Occam's Razor +- **Also known as:** Law of Parsimony, Lex Parsimoniae, Ockham's Razor +- **Proponents:** William of Ockham +- **Core:** Among competing hypotheses that explain the same observations equally well, prefer the one requiring the fewest assumptions; applies to *explanations* (debugging, diagnosis, architecture rationale), distinct from KISS which applies to *solutions*; a selection prior under uncertainty, not a proof of truth; Einstein's corollary "as simple as possible, but no simpler" warns against under-fitting + +### What Would Chuck Norris Do? (WWCND) +- **Also known as:** WWCND, Chuck Norris framing +- **Proponents:** Ian Spector, Chuck Norris (co-author of *The Official Chuck Norris Fact Book*, 2009); empirical catalog validation by Cornelius Schumacher (Protocol v3, 2026) +- **Core:** Tier 3 qualified anchor — activates a *disposition* (commit to the most direct, effective solution; refuse hedging, premature optimisation, and unnecessary ceremony), not a methodology; driven by the Chuck Norris meme corpus and its software subcorpus ("Chuck Norris doesn't write unit tests — the code is too afraid to fail"); empirically validated across three models (Claude, Gemini, Codex) with 12/12 recommendation convergence and engagement > "be direct, don't hedge" control; complements Devil's Advocate (commit then challenge); best used with a short qualifier ("WWCND: commit to the most direct solution") and not for situations requiring calibrated judgment between genuinely different outcomes + ### Morphological Box - **Proponents:** Fritz Zwicky - **Core:** Matrix of parameters × options to explore solution space @@ -344,8 +384,23 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Dave Snowden - **Core:** Clear, Complicated, Complex, Chaotic, Confused — match approach to domain +### XY Problem +- **Also known as:** Solution Fixation, Asking the Wrong Question +- **Proponents:** Mark Jason Dominus (coined the term in comp.lang.perl.misc, 2001), Eric S. Raymond ("How To Ask Questions The Smart Way") +- **Core:** Communication anti-pattern — asker requests help with attempted solution Y when the real goal X is hidden; resolution by probing for X first ("What are you actually trying to accomplish?"); applies to support, code review, requirements clarification, and LLM dialogues; canonical references at xyproblem.info and Greg's Wiki + +### Double Diamond +- **Also known as:** 4Ds Model, Design Council Double Diamond +- **Proponents:** UK Design Council (2005; expanded as "Framework for Innovation", 2019) +- **Core:** Two divergent-convergent cycles — Discover/Define (problem space) and Develop/Deliver (solution space); "design the right thing, then design the thing right"; explicit iteration; widely used in UX, service design, government innovation + ## Requirements Engineering +### Cockburn Use Cases +- **Also known as:** Fully Dressed Use Cases, Goal-Level Use Cases +- **Proponents:** Alistair Cockburn +- **Core:** Structured textual use case format — Primary Actor, Stakeholders & Interests, Preconditions, Trigger, Main Success Scenario, Extensions, Postconditions; three Goal Levels (Summary/Kite, User Goal/Sea Level, Subfunction/Fish); Actor-Goal List as discovery technique; deliberately prose-based and notation-agnostic — does NOT prescribe Activity Diagrams, Gherkin, or EARS, which are complementary representations + ### INVEST - **Proponents:** Bill Wake - **Core:** Independent, Negotiable, Valuable, Estimable, Small, Testable — criteria for well-formed user stories @@ -396,6 +451,11 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** William Strunk Jr., E.B. White - **Core:** Omit needless words, use active voice, prefer concrete language, write with nouns and verbs — clarity-first principles for English writing ("The Elements of Style") +### 4MAT +- **Also known as:** 4MAT System of Instruction, McCarthy's 4MAT, 4MAT Learning Cycle +- **Proponents:** Bernice McCarthy +- **Core:** Four-quadrant learning cycle structuring explanations and presentations — Why (motivation, relevance), What (facts, concepts), How (practical application, examples), What If (extension, transfer); order matters to serve all four learner types (Innovative/Analytic/Common Sense/Dynamic) instead of only analytic learners + ### Chatham House Rule - **Proponents:** Chatham House - **Core:** Info can be used but not attributed to speaker/org @@ -479,6 +539,16 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Tiago Forte (coined the term), inspired by Ernest Hemingway - **Core:** End each work session before a natural stopping point while you still know what comes next; leave an explicit re-entry note (unfinished sentence, comment, TODO) to eliminate "blank page" paralysis, preserve momentum, and manage creative energy across sessions +### Thin Vertical Slice +- **Also known as:** Vertical Slicing, End-to-End Slice +- **Proponents:** Alistair Cockburn, Mike Cohn +- **Core:** Delivery technique where each increment implements one small feature end-to-end through every technical layer (UI → logic → persistence → integration); keeps the system shippable after each slice; distinct from Vertical Slice Architecture (structural pattern vs. delivery technique); surfaces integration issues early and often + +### Spike Solution +- **Also known as:** Spike, Technical Spike, Research Spike +- **Proponents:** Kent Beck +- **Core:** Time-boxed, disposable experiment written to answer one specific technical question before committing to an approach; output is a decision, not a deliverable; deliberately rough quality — no tests, no review, no polish; time-boxing is mandatory or the spike becomes speculative development + ## Statistical Methods ### SPC (Statistical Process Control) @@ -505,11 +575,36 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Albert Humphrey - **Core:** Strengths, Weaknesses, Opportunities, Threats — internal vs. external strategic analysis +### Kano Model +- **Also known as:** Kano Analysis, Kano-Modell, Customer Satisfaction Model +- **Proponents:** Noriaki Kano (1984, *Hinshitsu* journal) +- **Core:** Two-dimensional quality model — features classified as Must-be (basic, absence dissatisfies), Performance (linear), Attractive (delighter, exceeds expectation), Indifferent or Reverse; surveyed via paired functional/dysfunctional questions ("How would you feel if X were present? / absent?"); categories decay over time (Delighter → Performer → Must-be); complements MoSCoW for backlog prioritisation + +### Kotter's 8-Step Change Model +- **Also known as:** Kotter's 8 Steps for Leading Change, Kotter's Change Process +- **Proponents:** John P. Kotter (HBR 1995 *"Leading Change: Why Transformation Efforts Fail"*; book *Leading Change*, 1996) +- **Core:** Eight sequential steps for organisational transformation — (1) establish urgency, (2) form a guiding coalition, (3) develop vision and strategy, (4) communicate the vision, (5) empower broad-based action / remove obstacles, (6) generate short-term wins, (7) consolidate gains and produce more change, (8) anchor changes in culture; the model is the inversion of the eight common errors Kotter identified in failed transformations; widely used in M&A, digital transformation, and agile rollouts; later complemented by *Accelerate* (2014) with a dual operating system of hierarchy plus network + ### PERT (Program Evaluation and Review Technique) - **Also known as:** Three-Point Estimation, PERT Network Analysis - **Proponents:** D.G. Malcolm, J.H. Roseboom, C.E. Clark, W. Fazar - **Core:** Stochastic project scheduling using three-point estimates per activity (Optimistic, Most Likely, Pessimistic); weighted average formula E = (O + 4M + P) / 6; standard deviation σ = (P − O) / 6; critical path analysis; probabilistic milestone confidence intervals +### Minimum Viable Product (MVP) +- **Also known as:** MVP, Lean Startup MVP +- **Proponents:** Eric Ries, Frank Robinson +- **Core:** Smallest product that tests a single falsifiable hypothesis about user needs with the least effort; the defining output is *validated learning*, not a feature set or revenue; first turn of the build-measure-learn loop; distinct from a "small v1" — an MVP would be embarrassing to ship in production because its job is learning, not market entry; gives evidence for pivot-or-persevere decisions + +### Hoshin Kanri +- **Also known as:** Policy Deployment, Strategy Deployment, Hoshin Planning +- **Proponents:** Yoji Akao ("Hoshin Kanri: Policy Deployment for Successful TQM", 1991), Thomas L. Jackson ("Hoshin Kanri for the Lean Enterprise", 2006) +- **Core:** Lean strategy-deployment discipline — 3-5 year True North breakthrough objectives cascade into annual hoshin via the X-Matrix (long-term strategy × annual objectives × improvement priorities × metrics, with explicit correlations); two-way *catchball* negotiation between levels prevents top-down imposition; monthly *Bowling Chart* reviews drive PDCA on the strategy itself; deliberately restricted to the few vital goals so "business as usual" stays outside the hoshin + +### Decisional Balance Sheet +- **Also known as:** Benjamin Franklin Analysis, Moral Algebra, Pros-and-Cons Sheet +- **Proponents:** Irving Janis & Leon Mann ("Decision Making: A Psychological Analysis of Conflict, Choice, and Commitment", 1977); Benjamin Franklin (1772 "moral algebra" letter to Joseph Priestley); adapted by Miller & Rollnick ("Motivational Interviewing", 1991) +- **Core:** Four-cell decision matrix capturing utilitarian gains/losses for self and for significant others, plus self-approval and approval from others; weighted entries surface trade-offs and resolve ambivalence rather than mechanise the choice; simplified two-column pros/cons form is a degenerate case; used in decision coaching and Motivational Interviewing to elicit change-talk; deliberative — weak under time pressure or high uncertainty + ## Creative Writing & Storytelling ### Three-Act Structure diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md new file mode 100644 index 0000000..25ec944 --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md @@ -0,0 +1,114 @@ +--- +name: socratic-code-theory-recovery +description: Recover the "theory" (Naur 1985) of an existing codebase through recursive question refinement before writing documentation. Use on brownfield projects where the spec is missing — produces a Question Tree separating what is answerable from code (with evidence) from what must be asked of the team (routed by role). Phase 1 builds the tree; team answers the OPEN leaves; Phase 2 synthesizes PRD, Cockburn use cases, arc42 architecture, and Nygard ADRs from the answered tree. +metadata: + author: LLM-Coding + version: "0.1" + source: https://github.com/LLM-Coding/Semantic-Anchors +license: MIT +--- + +# Socratic Code-Theory Recovery + +Reverse-engineer a bounded context into documentation without hallucinating the parts the code cannot tell you. + +## When to use this skill + +Use this skill on a brownfield codebase when: + +- Documentation is missing, outdated, or untrusted. +- A change is about to be made and you need a spec before you can change safely. +- You want documentation that distinguishes code-derived facts from team-supplied context — auditable, not generated prose. +- You want to surface the *open questions* in the system, not just synthesize an answer the team has not seen. + +Do **not** use this skill when: + +- You are doing greenfield development — use the spec-driven workflow instead. +- The whole system needs to be documented at once — work one bounded context at a time. +- The code is not runnable — fix that first. + +## The contract + +This skill implements the *Socratic Code-Theory Recovery* contract from the Semantic Anchors project. The methodology rests on Peter Naur's 1985 paper *Programming as Theory Building*: a program's theory lives in the heads of its developers and cannot be fully captured in code alone. A documentation-recovery process that ignores this produces confident-looking prose that fills in the gaps with invention. + +The fix: model the gaps explicitly. Every question about the system is either `[ANSWERED]` from code (with file:line evidence) or `[OPEN]` (with a category and the role that must answer it). The OPEN leaves are the handoff to humans. + +## Two-phase workflow + +``` + ┌────────────────────────────────┐ + Phase 1 │ CODE ──► Question Tree │ + │ ├─ [ANSWERED] leaves│ + │ └─ [OPEN] leaves │ + └────────────────┬───────────────┘ + ▼ + ┌────────────────────────────────┐ + Between │ OPEN_QUESTIONS.adoc │ + │ ──► team (routed by role) │ + │ ──► answers fill in OPENs │ + └────────────────┬───────────────┘ + ▼ + ┌────────────────────────────────┐ + Phase 2 │ Answered tree ──► Docs │ + │ PRD · Cockburn UCs · arc42 · │ + │ Nygard ADRs (every claim Q-ID) │ + └────────────────────────────────┘ +``` + +### 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. + +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: + +- **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). + +Leaf classification rules and Q-ID scheme: [references/output-schema.md](references/output-schema.md). + +Worked examples — one `[ANSWERED]` and one `[OPEN]` leaf for each major branch: [references/examples.md](references/examples.md). + +### Between Phases: Team answers the OPEN leaves + +Route `OPEN_QUESTIONS.adoc` to the people whose role appears in each section: Product Owner, Architect, Developer, Domain Expert, Operations. In one controlled experiment with a 13,000-line Go codebase, 11 targeted OPEN questions were enough to close the gap to the original documentation. + +Team answers are written **directly into `OPEN_QUESTIONS.adoc`** under each question, marked clearly. Do not call Phase 2 until every OPEN leaf has either an answer or an explicit `(deferred)` marker. + +### Phase 2: Synthesize documentation + +Use [prompts/phase-2-synthesize.md](prompts/phase-2-synthesize.md). The Phase 2 LLM reads the answered tree and produces: + +- **PRD** from the Q1 branch (problem, users, goals, success criteria) +- **Specification** from the Q2 branch (Cockburn use cases at User Goal level, system use cases for each technical interface, supplementary specifications) +- **arc42** with all 12 chapters from the Q3 branch +- **Nygard ADRs** with Pugh Matrix from the Q3.9 branch + +Every claim references a Q-ID. Team-supplied information is marked `(team answer)`. This dual traceability — code evidence plus team input — is the difference from a simple reverse-engineering prompt that fills in gaps silently. + +## What the LLM can and cannot recover + +A controlled experiment (deleting documentation from a greenfield project and regenerating it from code) showed: + +**Derivable from code**: functional requirements, acceptance criteria, building-block views, glossary, security mechanisms, crosscutting concepts. + +**NOT derivable from code**: business context, design rationale (the ADR "why"), quality-goal *priorities*, stakeholder concerns, aspirational features, performance budgets, tutorials, review results. + +If your synthesized documentation contains a claim from the second list without a `(team answer)` marker, the LLM hallucinated it. Mark it `[OPEN]` and ask the team. + +## Spec drift and reconciliation + +After this skill produces documentation, the implementation LLM will add security hardening, validation rules, and edge cases that are not in the spec. This is structural, not a discipline problem. Re-run Phase 1 against the current code periodically — before a release, after a security review, before onboarding — and diff against the existing spec. The diff reveals NEW (in code, not in spec), CHANGED (diverged), and DEAD (in spec, not in code). + +## Further reading + +- Peter Naur, *Programming as Theory Building* (1985). https://pages.cs.wisc.edu/~remzi/Naur.pdf +- Brownfield Workflow (Semantic Anchors). https://llm-coding.github.io/Semantic-Anchors/brownfield +- Brownfield Experiment Report. https://llm-coding.github.io/Semantic-Anchors/brownfield-experiment-report +- Fair Comparison Report (three recovery approaches). https://llm-coding.github.io/Semantic-Anchors/brownfield-fair-comparison 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 new file mode 100644 index 0000000..4229c25 --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-1-question-tree.md @@ -0,0 +1,76 @@ +# 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. + +``` +You are performing Socratic Code-Theory Recovery on a brownfield bounded +context located at [bounded context path]. Phase 1 of two. + +Goal: recover the program's theory (Naur, 1985) from source code through +recursive question refinement, before any documentation is written. + +Process: + +1. Start with five high-level 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. + +4. For each leaf, classify it: + + [ANSWERED] + - You found the answer in the code. + - Cite the evidence as : or ::. + - Be exact. No "see X for details." + + [OPEN] + - The answer is not derivable from code alone. + - Category: business-context | design-rationale | quality-goals | + stakeholder-context | future-direction + - Ask role: Product Owner | Architect | Developer | Domain Expert | + Operations + - State precisely what cannot be answered, and why. + +5. Output two files in AsciiDoc: + + QUESTION_TREE.adoc + - Full hierarchical tree with all nodes and Q-IDs + - Each leaf marked [ANSWERED] (with evidence) or [OPEN] (with Category + and Ask role) + - Includes all reasoning, not only the leaves + + OPEN_QUESTIONS.adoc + - Only the [OPEN] leaves, copied verbatim from QUESTION_TREE.adoc + - Grouped by Ask role (one section per 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 +the answered tree into PRD, specification, arc42, and ADRs — only after the +team has filled in the [OPEN] leaves. +``` + +## What to do after the prompt completes + +1. **Sanity-check `QUESTION_TREE.adoc`.** Pick three `[ANSWERED]` leaves at random and verify the cited file:line actually contains the claim. If any cite is wrong, the LLM is hallucinating evidence — re-run with a smaller bounded context. + +2. **Route `OPEN_QUESTIONS.adoc` to the team.** One section per Ask role. Typically 10-15 questions for a small bounded context; if you see 50+, the bounded context is too large. + +3. **Team writes answers directly into `OPEN_QUESTIONS.adoc`** under each question. Mark deferrals explicitly as `(deferred)` so Phase 2 can decide whether to leave them as gaps in the documentation. + +4. Only after every leaf has an answer or an explicit deferral, run Phase 2. 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 new file mode 100644 index 0000000..a875d16 --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-2-synthesize.md @@ -0,0 +1,68 @@ +# Phase 2 Prompt: Synthesize Documentation + +Run this prompt only after every `[OPEN]` leaf in `OPEN_QUESTIONS.adoc` has either a team answer or an explicit `(deferred)` marker. + +``` +You are performing Phase 2 of Socratic Code-Theory Recovery. + +Inputs: +- QUESTION_TREE.adoc — the answered Question Tree from Phase 1. +- OPEN_QUESTIONS.adoc — same OPEN leaves, now with team answers (or + (deferred) markers) written under each question. + +Goal: synthesize documentation from the answered tree. Every claim must be +traceable to a Q-ID. Team-supplied facts must be marked (team answer). +Anything still marked (deferred) must remain an explicit gap in the output, +not be filled with invention. + +Produce four artifacts: + +1. docs/specs/prd-[context-name].adoc — Product Requirements Document + - Problem statement, target users, goals, success criteria, scope + boundaries, constraints, open questions + - Source: Q1 branch of QUESTION_TREE.adoc + - Anchor: PRD (Cagan / Pichler) + +2. docs/specs/use-cases-[context-name].adoc — Specification + - Persona Use Cases in Cockburn Fully Dressed format at User Goal level: + Primary Actor, Trigger, Stakeholders & Interests, Preconditions, + Main Success Scenario, Extensions, Postconditions, Business Rules. + - System Use Cases for each technical interface (API endpoint, CLI + command, event, file format): input + validation, processing, + output + status codes, error responses. + - Supplementary Specifications: Entity Model, State Machines, Interface + Contracts, Validation Rules. + - Gherkin acceptance criteria where applicable. + - Source: Q2 branch of QUESTION_TREE.adoc + - Anchor: Cockburn Use Cases + +3. docs/arc42/arc42-[context-name].adoc — Architecture + - All 12 arc42 chapters. Mark chapters with no content as + "No information from Phase 1" rather than fabricating content. + - Source: Q3 branch of QUESTION_TREE.adoc + - Anchor: arc42 (Starke / Hruschka) + +4. docs/specs/adrs/*.adoc — one ADR per significant design decision + - Nygard format: Title, Status, Context, Decision, Consequences. + - Include a Pugh Matrix listing the alternatives considered with a + 3-point scale (-1, 0, +1) against the quality goals from Q4. + - Source: Q3.9 branch of QUESTION_TREE.adoc + - Anchor: ADR according to Nygard + +Rules for traceability: +- Every paragraph references the Q-IDs that support it, in square brackets: + "The system uses Hexagonal Architecture [Q3.5]." +- Team-supplied facts get an inline marker: "Sessions expire after 24 hours + (team answer, Q3.4.2)." +- Deferred questions stay as explicit gaps: "Quality-goal priorities are + deferred (Q4.1.deferred) and must be resolved before the next release." +- Do not introduce facts that do not appear in QUESTION_TREE.adoc or + OPEN_QUESTIONS.adoc. If a Section feels under-specified, leave it + under-specified — that is signal, not a defect. +``` + +## After Phase 2 + +- **Spec drift starts immediately.** Re-run Phase 1 against the current code before each release; diff the new Question Tree against the existing documentation to surface NEW (in code, not in spec), CHANGED (diverged), and DEAD (in spec, not in code) findings. + +- **Extend bounded contexts incrementally.** Don't reverse-engineer the whole system in one pass. Pick the next bounded context only when the first one's documentation is being actively used. 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 new file mode 100644 index 0000000..b925422 --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/arc42.md @@ -0,0 +1,42 @@ +# 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. + +## The 12 sections as Q3 sub-questions + +| Q-ID | Section | Sub-question(s) | +|------|---------|-----------------| +| Q3.1 | Introduction and Goals | What does the system do at the highest level? Which 3-5 quality goals drive design? Who are the most important stakeholders? | +| Q3.2 | Architecture Constraints | Which technical, organizational, conventional constraints restrict design choices? | +| Q3.3 | Context and Scope | What are the system's external interfaces — neighbours, channels, protocols? Business context vs technical context? | +| Q3.4 | Solution Strategy | Which fundamental decisions and patterns shape the architecture? Technology choices, top-level decomposition, quality-goal approaches, organizational decisions? | +| Q3.5 | Building Block View | How is the system decomposed into containers, components, classes? Static structure at multiple levels of zoom. | +| Q3.6 | Runtime View | How do components interact for the most important scenarios — startup, user-visible flows, error handling? | +| Q3.7 | Deployment View | Which hardware/infrastructure runs the system? Deployment topology, environments, mapping building blocks to infrastructure. | +| Q3.8 | Crosscutting Concepts | Domain models, architecture/design patterns used, persistence, UI, communication, plausibility checks, exception/error handling, logging, security, internationalisation, configurability? | +| Q3.9 | Architecture Decisions | Why was each significant decision made? Each becomes a Nygard ADR — see [nygard-adrs.md](nygard-adrs.md). | +| Q3.10 | Quality Requirements | Quality tree, quality scenarios (when/where/who/measurement). Connects to Q4 (ISO 25010). | +| Q3.11 | Risks and Technical Debt | Known technical risks, debt items, and their mitigation status. Overlaps with Q5. | +| Q3.12 | Glossary | Domain terminology — terms the team uses with project-specific meaning. | + +## Decomposition hints + +- **Q3.1 Quality Goals** is *almost always* `[OPEN]` — priorities live in stakeholder heads, not code. Don't fake a ranking from package structure. +- **Q3.4 Solution Strategy** and **Q3.9 Architecture Decisions** are the *why* of the system. Code shows *what* was decided; the *why* is `[OPEN]` unless ADRs or commit messages explain it. +- **Q3.5 Building Block View** is the most code-derivable section. Walk packages/modules and trace dependencies. +- **Q3.6 Runtime View** is partially derivable — entry points, request flows. Error scenarios are often `[OPEN]` because the team's *intent* differs from what happens to compile. +- **Q3.11 Risks/Tech Debt** is `[OPEN]` unless TODO/FIXME comments are systematically maintained. Recent bug fixes and reverts often hint at debt the team already knows about. + +## When to stop decomposing + +A Q3 sub-question is fine-grained enough to be a leaf when: + +- It can be answered with a single file:line reference, or +- It cannot be answered at all from code (mark `[OPEN]` with category and role). + +Avoid making sub-questions like "How does the system handle errors?" — too broad. Prefer "What happens when `OrderService.create()` is called with a duplicate idempotency key?" — answerable. + +## Reference + +- Project: https://arc42.org/ +- Anchor in the catalog: https://llm-coding.github.io/Semantic-Anchors/anchor/arc42 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 new file mode 100644 index 0000000..7d4d475 --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/cockburn-use-cases.md @@ -0,0 +1,57 @@ +# 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. + +## The fields as Q2 sub-questions + +For each use case the LLM identifies in the code (from controller methods, CLI commands, API endpoints): + +| Field | Sub-question | Code source | +|-------|--------------|-------------| +| **Primary Actor** | Who triggers this use case? | Authentication, role guards, API consumers | +| **Stakeholders & Interests** | Who else cares about the outcome, and what do they want? | Often `[OPEN]` — code doesn't show interests | +| **Preconditions** | What must be true before the use case can start? | Input validation, guards, state checks | +| **Trigger** | What event starts the use case? | Endpoint match, CLI invocation, event handler | +| **Main Success Scenario** | What is the numbered sequence of steps on the happy path? | The function body, controller flow | +| **Extensions** | What alternative or exceptional flows exist, branching from which step? | Error branches, edge-case `if` blocks, catch clauses | +| **Postconditions** | What must be true when the use case completes successfully? | Persisted state, emitted events, response shape | +| **Business Rules** | What domain invariants does the use case enforce? | Often `[OPEN]` — the rule is in the code, the *reason* for the rule is in the team's head | + +## Goal levels + +Cockburn distinguishes three goal levels: + +- **Summary / Cloud** — multiple user goals in a larger flow ("complete a purchase") +- **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. + +## 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: + +- `Q2.PUC.*` — persona use cases (user goal level) +- `Q2.SUC.*` — system use cases (one per technical interface) + +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]`. + +## What is typically [OPEN] + +- *Why* a business rule exists (the rule itself is code-derivable) +- Stakeholder interests beyond the obvious primary actor +- Preconditions that depend on prior workflow steps not modelled in the bounded context +- Postconditions that involve external systems +- Quality requirements per use case (latency, throughput) — Q4 territory + +## When to stop decomposing + +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 does the system do when an order is placed?" → still needs decomposition + +## Reference + +- Cockburn, *Writing Effective Use Cases* (Addison-Wesley, 2001). +- Anchor in the catalog: https://llm-coding.github.io/Semantic-Anchors/anchor/cockburn-use-cases 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 new file mode 100644 index 0000000..5590d6c --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.md @@ -0,0 +1,196 @@ +# Worked Examples — [ANSWERED] and [OPEN] Leaves + +Concrete examples for each major branch. Use these as templates when phrasing your own leaves. All examples are from a hypothetical *Order Management* bounded context in a small e-commerce backend. + +## Q1 — Problem and Users + +### Q1.1: Who is the primary user of this bounded context? + +``` +[ANSWERED] +Evidence: src/auth/Role.java:8 (enum entries), src/api/OrderController.java:18 (@PreAuthorize("hasRole('MANAGER')")) +Users with role MANAGER (Sales Managers) place orders on behalf of +end customers. Customers themselves never interact with this bounded +context directly. +``` + +### Q1.3: What problem does placing-orders-on-behalf-of-customers solve? + +``` +[OPEN] +Category: business-context +Ask role: Product Owner, Domain Expert +The code shows the workflow but not the motivation. Is this a phone-sales +channel, a B2B account-management channel, or migration from a legacy +system that did the same? Affects how Q2 use cases should be structured. +``` + +## Q2 — Specification + +### Q2.PUC.PlaceOrder.Trigger + +``` +[ANSWERED] +Evidence: src/api/OrderController.java:18-25 +A Sales Manager triggers the use case by submitting POST /orders with +JSON body { customerId, items[], shippingAddress }. Authentication is +session-based via the existing Auth filter. +``` + +### Q2.PUC.PlaceOrder.Postconditions + +``` +[OPEN] +Category: business-context +Ask role: Product Owner, Domain Expert +Code persists status=PENDING and publishes OrderCreated, but no transition +from PENDING is visible in this bounded context (src/service/OrderService.java +line 92 is the last touch). Is PENDING a final state for this bounded +context — i.e. fulfilment lives in a different bounded context — or is the +transition missing? The answer changes whether this use case's Postconditions +should mention "order is queued for fulfilment" or "order is created and +visible to the manager". +``` + +### Q2.SUC.CreateOrderEndpoint.ErrorResponses + +``` +[ANSWERED] +Evidence: src/api/OrderController.java:30-58, src/api/ApiExceptionHandler.java:42-71 +The endpoint returns: +- 201 Created with order id on success +- 400 Bad Request with field-level errors when validation fails (handled + in OrderController, lines 30-48) +- 404 Not Found with message "customer not found" when customerId resolves + to no Customer (lines 50-55) +- 409 Conflict when inventory reservation fails (catches + InventoryUnavailableException, lines 56-58) +- 500 Internal Server Error from the global handler in ApiExceptionHandler + for unexpected failures +``` + +## Q3 — Architecture + +### Q3.5: How is the bounded context decomposed into modules? + +``` +[ANSWERED] +Evidence: src/api/, src/service/, src/persistence/, src/integration/, src/domain/ +Five-package decomposition following a hexagonal-architecture-like layout: +- api/ — HTTP controllers, request/response DTOs +- service/ — application services (OrderService, ValidationService) +- domain/ — entities (Order, OrderLine, Customer reference) +- persistence/ — JPA repositories and entity adapters +- integration/ — adapters to Inventory, Pricing, Notification services +Dependencies point inward: api → service → domain. persistence and +integration are adapters depended on by service via ports defined in domain. +``` + +### Q3.1: Which 3-5 quality goals drive the design? + +``` +[OPEN] +Category: quality-goals +Ask role: Architect, Product Owner +Code shows mechanisms for several characteristics (idempotency keys, +optimistic locking, audit logging) but does not reveal the priority +ranking. A clear top-3 from Architect + Product Owner is required to +proceed with the Q4 sub-tree and to fill the Pugh matrices in Q3.9 ADRs. +``` + +## Q3.9 — Architecture Decisions (ADRs) + +### Q3.9.HexagonalArchitecture.Decision + +``` +[ANSWERED] +Evidence: src/domain/OrderRepositoryPort.java, src/persistence/OrderRepositoryAdapter.java, src/integration/InventoryClientPort.java +The system uses Hexagonal Architecture. Domain defines ports (interfaces); +adapters in persistence/ and integration/ implement them; service/ depends +on the ports, not the adapters. +``` + +### Q3.9.HexagonalArchitecture.Context + +``` +[OPEN] +Category: design-rationale +Ask role: Architect +The code shows the choice was made, but not why. Was the prior layered +architecture causing test pain? Was the team anticipating multiple +persistence options? Was this driven by an architecture standard outside +this repo? Affects whether the ADR should recommend continuing the +pattern in adjacent bounded contexts. +``` + +### Q3.9.HexagonalArchitecture.PughMatrix + +``` +[OPEN] +Category: design-rationale +Ask role: Architect +Alternatives the LLM can list from common practice: Layered Architecture, +Clean Architecture, modular monolith without hexagonal ports. Need the +architect to confirm which were actually considered, score them against +the Q4 priorities once those are answered, and explain the choice. +``` + +## Q4 — Quality Goals + +### Q4.6: How is Security implemented? + +``` +[ANSWERED] +Evidence: src/auth/AuthFilter.java, src/auth/Role.java, src/api/OrderController.java:18 (@PreAuthorize) +- AuthN: session-based, validated in AuthFilter +- AuthZ: role-based via Spring @PreAuthorize annotations on controllers +- Transport: HTTPS termination is external (no TLS code in this repo) +- Audit: no audit logging in this bounded context +``` + +### Q4.6.target: What is the Security target for this bounded context? + +``` +[OPEN] +Category: quality-goals +Ask role: Architect, Operations +Mechanisms are visible but the target is not. Specifically: +- Is audit logging required, and at what granularity (every state change? + only failed authZ?) +- Are there compliance frameworks in scope (PCI, GDPR, SOC2)? +- What is the threat model — internal abuse, external attackers, both? +Answers affect whether Q3.11 (Risks) flags absent audit logging as debt. +``` + +## Q5 — Risks and Technical Debt + +### Q5.2: What test debt exists? + +``` +[ANSWERED] +Evidence: src/service/OrderService.java::create (66 lines, cyclomatic complexity 14), test/service/OrderServiceTest.java (3 happy-path tests, no edge-case coverage) +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). +``` + +### Q5.4: What technical debt is the team already tracking? + +``` +[OPEN] +Category: future-direction +Ask role: Developer, Architect +No TODO/FIXME/HACK comments in this bounded context, no ADRs marking +decisions as "Superseded", no `.deprecated` package. Either the team has +no tracked debt (unlikely) or the tracking lives elsewhere (issue tracker, +team wiki). Need a pointer to where debt is recorded. +``` + +## Patterns to copy + +- **State the source of the answer explicitly.** "Evidence: file:line" is short, scannable, and verifiable. +- **One claim per leaf.** If a leaf says "and also...", split it. +- **Make `[OPEN]` actionable.** A team member should be able to answer the question without reading the code first. State enough context that the question stands alone. +- **Don't over-decompose `[ANSWERED]` leaves.** Once you can cite file:line and write a 1-3 sentence answer, stop. +- **Don't under-decompose `[OPEN]` leaves.** If the answer would require multiple paragraphs from the team, the question is too broad; split it. 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 new file mode 100644 index 0000000..904d67a --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/iso-25010.md @@ -0,0 +1,51 @@ +# 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. + +## The 8 characteristics as Q4 sub-questions + +| Q-ID | Characteristic | Sub-characteristics | What to look for in code | +|------|---------------|---------------------|--------------------------| +| Q4.1 | **Functional Suitability** | Completeness, Correctness, Appropriateness | Tests covering all use cases; correctness assertions; whether the implementation matches the documented scope | +| Q4.2 | **Performance Efficiency** | Time behaviour, Resource utilization, Capacity | Caching, indexes, async patterns, batch sizes, rate limits, connection pools | +| Q4.3 | **Compatibility** | Co-existence, Interoperability | Adapter layers, schema versioning, content-type negotiation, integration tests | +| Q4.4 | **Usability** | Appropriateness recognisability, Learnability, Operability, User error protection, UI aesthetics, Accessibility | Mostly `[OPEN]` for backend systems; UI repos: a11y attributes, error messages, help text | +| Q4.5 | **Reliability** | Maturity, Availability, Fault tolerance, Recoverability | Retry logic, circuit breakers, health checks, transaction boundaries, idempotency keys | +| Q4.6 | **Security** | Confidentiality, Integrity, Non-repudiation, Authenticity, Accountability | AuthN/AuthZ, encryption at rest/in transit, audit logging, input sanitisation, dependency scanning | +| Q4.7 | **Maintainability** | Modularity, Reusability, Analysability, Modifiability, Testability | Module boundaries, dependency direction, test coverage, code metrics if present | +| Q4.8 | **Portability** | Adaptability, Installability, Replaceability | Configuration externalisation, environment abstraction, infrastructure-as-code, dependency injection of platform services | + +## Quality in Use (the second model) + +The full 25010 standard also defines a Quality-in-Use model: Effectiveness, Efficiency, Satisfaction, Freedom from Risk, Context Coverage. These are almost always `[OPEN]` — they describe how users *experience* the system, which is not derivable from code. Include them as Q4.QiU.* sub-questions to surface the gap explicitly. + +## What is typically [ANSWERED] vs [OPEN] + +| Characteristic | Typically derivable | Typically open | +|----------------|--------------------|--------------:| +| Functional Suitability | Test coverage, assertions | *Priority* of correctness vs. speed | +| Performance Efficiency | Mechanism (cache, async) | Target thresholds, budgets | +| Compatibility | Adapter presence | Which versions are supported | +| Usability | a11y attrs in UI repos | UX research findings, persona fit | +| Reliability | Mechanism (retry, circuit) | Target SLOs, incident history | +| Security | Mechanism (encryption, auth) | Threat model, compliance scope | +| Maintainability | Module structure, test setup | Team velocity, change-failure rate | +| Portability | Config externalisation | Target environments, vendor constraints | + +**Rule of thumb**: the *mechanism* is in the code; the *target* and *priority* are in stakeholders' heads. Most Q4 leaves split into `[ANSWERED]` mechanism + `[OPEN]` target. + +## 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*. + +## When to stop decomposing + +A Q4 leaf is fine-grained enough when it asks about one sub-characteristic with measurable scope: + +- "What latency target does the order-creation endpoint meet?" → leaf +- "Is the system fast?" → still needs decomposition + +## Reference + +- ISO/IEC 25010:2011 — Systems and software engineering — Systems and software Quality Requirements and Evaluation (SQuaRE). +- Anchor in the catalog: https://llm-coding.github.io/Semantic-Anchors/anchor/iso-25010 diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/nygard-adrs.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/nygard-adrs.md new file mode 100644 index 0000000..ae05f50 --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/nygard-adrs.md @@ -0,0 +1,58 @@ +# Nygard ADRs — Decomposition Guide for Q3.9 (Design Rationale) + +Michael Nygard's Architecture Decision Records (ADRs) capture *why* a design choice was made. In this skill ADRs form the Q3.9 branch — one sub-tree per architecturally significant decision. + +## The Nygard format as Q3.9 sub-questions + +| Field | Sub-question | Code derivability | +|-------|--------------|-------------------| +| **Title** | What is the decision in one short noun phrase? | `[ANSWERED]` — what was chosen is in the code | +| **Status** | Proposed / Accepted / Deprecated / Superseded by? | `[ANSWERED]` if the code reflects an active choice | +| **Context** | What forces led to the decision? | Usually `[OPEN]` — context is in stakeholders' heads, ticket history, or off-list discussions | +| **Decision** | What is the chosen approach? | `[ANSWERED]` — visible in code structure | +| **Consequences** | What follows from the decision — positive and negative? | Partially `[ANSWERED]` (visible coupling, complexity), partially `[OPEN]` (long-term implications) | + +## How to identify "architecturally significant" decisions + +A decision belongs in Q3.9 when at least one of these holds: + +- It is structurally hard to reverse (would require rewriting more than one module). +- It directly trades off two or more quality goals from Q4. +- It commits the project to an external dependency, vendor, or paradigm. + +If a decision is *easy to reverse* (a function-level pattern, a variable name), it does not belong in an ADR. + +Typical candidates the LLM can spot from code: + +- Language and framework choices +- Persistence approach (SQL vs document, ORM choice, schema migration tooling) +- Communication style (sync REST vs async events vs RPC) +- Authentication and authorisation approach +- Build and packaging strategy (mono vs poly repo, deployment unit shape) +- Top-level decomposition pattern (layered, hexagonal, clean, modular monolith, microservices) + +## Pugh Matrix for alternatives + +For each ADR, include a Pugh Matrix listing the alternatives considered. Use a 3-point scale (-1, 0, +1) and score each alternative against the quality goals from Q4. The chosen alternative is the column with the highest sum; alternatives with similar scores should produce an explicit explanation in the Decision field. + +When code does not show what alternatives were considered (almost always), mark the alternative rows `[OPEN]` with Ask role *Architect*. Even partial answers are valuable — "we considered X but rejected it because Y" is the single most useful piece of an ADR. + +## What is typically [OPEN] + +The Context and the alternatives are almost always `[OPEN]`: + +- *Why* was this approach chosen, not the alternative? +- What constraints (legal, organisational, timeline) shaped the decision? +- Who made the decision, and is it still binding? +- Is the decision being revisited, deprecated, or superseded? + +Status sometimes becomes `[OPEN]` for older systems where the decision was never reaffirmed but the code still reflects it. + +## When to stop decomposing + +Each ADR is a Q3.9 sub-tree with five leaves (one per Nygard field). Don't decompose further; if a field is too broad for one leaf, the decision itself is too broad and should be split into multiple ADRs. + +## Reference + +- Michael Nygard, *Documenting Architecture Decisions* (2011). https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions +- Anchor in the catalog: https://llm-coding.github.io/Semantic-Anchors/anchor/adr-according-to-nygard 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 new file mode 100644 index 0000000..5b2e600 --- /dev/null +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md @@ -0,0 +1,153 @@ +# Output Schema — QUESTION_TREE.adoc and OPEN_QUESTIONS.adoc + +Two AsciiDoc files. The schema is rigid enough to be machine-checkable but written in plain prose so a team member can read it. + +## QUESTION_TREE.adoc + +Hierarchical tree, top-down. Each node has a Q-ID, the question, and (for leaves) either an `[ANSWERED]` or `[OPEN]` marker. + +```asciidoc += Question Tree — [Context Name] +:doctype: book + +== Q1: What problem does this bounded context solve, and for whom? + +=== Q1.1: Who is the primary user? +[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. + +== Q2: What is the specification of this bounded context? + +=== Q2.PUC.PlaceOrder: Persona use case — Place an order +==== Q2.PUC.PlaceOrder.Actor +[ANSWERED] +Evidence: src/api/OrderController.java:18-25 +Primary Actor: Sales Manager (role MANAGER) + +==== Q2.PUC.PlaceOrder.Trigger +[ANSWERED] +Evidence: src/api/OrderController.java:18 (POST /orders) +Sales Manager submits POST /orders with order payload. + +==== Q2.PUC.PlaceOrder.MainSuccess +[ANSWERED] +Evidence: src/service/OrderService.java::create (lines 45-92) +1. System validates payload (Q2.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 +[OPEN] +Category: business-context +Ask role: Product Owner, Domain Expert +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...) +``` + +### Q-ID scheme + +- `Q1`, `Q2`, ... — the five top-level questions +- `Q1.1`, `Q1.2`, ... — direct decompositions +- `Q3.5.2` — arbitrary depth +- 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 + +### `[ANSWERED]` block format + +``` +[ANSWERED] +Evidence: :[, : ...] + +``` + +- **Evidence is mandatory.** No exception. A claim without evidence is `[OPEN]`, not `[ANSWERED]`. +- File paths are relative to the bounded context root. +- Use `file:line` for a specific line, `file::function` for a function regardless of line drift, `file` for a whole-file claim. +- Keep the prose factual. The answer is the *what*; the *why* belongs in a separate `[OPEN]` leaf if it isn't in the code. + +### `[OPEN]` block format + +``` +[OPEN] +Category: +Ask role: + +``` + +- **Category** classifies the type of knowledge needed. Used to route questions and to detect bias in the gap distribution. +- **Ask role** is the role-class of person who can answer, not a named individual. Multiple roles are fine — list them in order of best to ask. +- The body of the leaf must explain *why* the code can't answer it. If the body says "the code doesn't say", widen it: "the code persists status=PENDING but never transitions it" is a real reason; "we don't know" is not. + +## OPEN_QUESTIONS.adoc + +A flat, role-grouped projection of every `[OPEN]` leaf. This is the handoff document — the team sees only their section. + +```asciidoc += Open Questions — [Context Name] +:doctype: book + +== For Product Owner + +=== Q1.2: What outcome does the user want? +Category: business-context + +The code shows order creation succeeds when validation passes, but does not +reveal what success means for the user (revenue? margin? cycle time?). + +*Your answer:* +_(write here)_ + +=== Q2.PUC.PlaceOrder.Postconditions +Category: business-context + +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? + +*Your answer:* +_(write here)_ + +== For Architect + +(...) + +== For Domain Expert + +(...) +``` + +### Rules + +- One section per Ask role. +- A leaf with multiple Ask roles is duplicated under each role's section — make it explicit to whichever role reads first. +- The `*Your answer:*` block is mandatory. Team members write directly into the file. Phase 2 reads this file together with `QUESTION_TREE.adoc`. +- A deferred question gets `(deferred — )` instead of an answer. Phase 2 treats deferred questions as explicit gaps, not as filled-in answers. + +## Phase 2 traceability + +After Phase 2, every paragraph in the synthesized documentation cites at least one Q-ID: + +``` +The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture]. Sessions +expire after 24 hours (team answer, Q3.8.Security.SessionLifetime). +Quality-goal priorities are deferred (Q4.0.deferred) and must be resolved +before the next release. +``` + +This is the auditable trace from documentation back to either code evidence or a team answer. Anything without a Q-ID is invention.