Merge pull request #476 from raifdmueller/feat/brownfield-prompt-block-472

docs: brownfield Phase 0.5 — copy-paste prompt block + hyphenate title (#472)

Author: rdmueller

docs/brownfield-workflow.adoc

@@ -53,33 +53,85 @@ Present as a table.
 Pick one bounded context to start with.
 Choose one that is small, well-isolated, and has a change request pending.
 
-== Phase 0.5: Socratic Code Theory Recovery
+== Phase 0.5: Socratic Code-Theory Recovery
 
 Before changing anything, you need to recover the "theory" of the bounded context -- what https://pages.cs.wisc.edu/~remzi/Naur.pdf[Peter Naur] called the mental model that lives in the heads of the original developers. In a brownfield project, this model is not documented. The code is the only source.
 
-This phase uses *Socratic Code Theory Recovery*: a two-phase workflow that builds understanding through recursive question refinement before producing documentation.
+This phase uses *Socratic Code-Theory Recovery*: a two-phase workflow that builds understanding through recursive question refinement before producing documentation.
 
 === 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.
 
-.Starting Questions (adapt to your bounded context)
+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).
+
+Copy the prompt below into a session that has read access to the bounded context. Adapt `[bounded context path]` and the example questions if your domain warrants it; do not change the leaf classification, Q-ID scheme, or output files.
+
+.Prompt: Phase 1 — Build the Question Tree
 [source,txt]
 ----
-1. What problem does this bounded context solve and for whom?
-2. What is the specification of this bounded context?
-3. What is the architecture of this bounded context?
-4. What quality goals drive the design?
-5. What risks and technical debt exist?
+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 <file>:<line> or <file>::<function>.
+     - 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.
 ----
 
-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 files:
-
-* `QUESTION_TREE.adoc` -- the full reasoning trace
-* `OPEN_QUESTIONS.adoc` -- the handoff document, grouped by role (Product Owner, Architect, Developer, Domain Expert, Operations)
-
 === Between Phases: Team Answers the Open Questions
 
 Route the Open Questions to the people who can answer them. In a controlled experiment with a 13,000-line Go codebase, *11 targeted questions* were sufficient to close the gap between reverse-engineered documentation and the original. The questions are precise because the recursive decomposition ensures they are specific, not vague.
@@ -233,6 +285,6 @@ If the system cannot be built or started, you have a different problem -- fix th
 * Simon Martinelli, https://unifiedprocess.ai/[AI Unified Process] -- the bounded-context approach to spec-driven development in existing systems.
 * Eric Evans, https://www.domainlanguage.com/ddd/[Domain-Driven Design] -- the foundational work on bounded contexts and strategic design.
 * Michael Feathers, _Working Effectively with Legacy Code_ -- techniques for establishing test coverage in systems without tests.
-* Peter Naur, "Programming as Theory Building" (1985) -- argues that programming is about building a mental model ("theory") that cannot be fully captured in documentation. Socratic Code Theory Recovery tests this claim in the context of LLM-generated code.
+* Peter Naur, "Programming as Theory Building" (1985) -- argues that programming is about building a mental model ("theory") that cannot be fully captured in documentation. Socratic Code-Theory Recovery tests this claim in the context of LLM-generated code.
 * link:#/brownfield-experiment-report[Brownfield Experiment Report] -- controlled experiment: delete documentation from a greenfield project, regenerate from code, compare. Full methodology and findings.
 * link:#/brownfield-fair-comparison[Fair Comparison Report] -- three approaches (Direct, Socratic, Two-Phase) with identical team answers. Measures the structural value of the Question Tree.