From 5d67dc1ee31b0783c7e5252e997ac552aafc1884 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Tue, 16 Jun 2026 07:24:06 +0200 Subject: [PATCH 1/5] feat(workflows): add socratic-recovery workflow and cockburn-use-cases template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds two new files: - resources/workflows/socratic-recovery.yaml — 5-state brownfield architecture recovery workflow based on Socratic Code-Theory Recovery (Naur, 1985 / Ralf Müller blog post). States: question_tree → answer_open_questions → synthesize_documentation → review_and_rework → recovery_done Embeds Phase 1 and Phase 2 prompts verbatim. Produces arc42, PRD, Cockburn use-case spec, and Nygard ADRs. The OPEN_QUESTIONS file is the primary deliverable — gaps are never invented. - resources/templates/requirements/cockburn-use-cases.md — lean Fully Dressed use-case template (Cockburn) with Persona Use Cases (UC-P##), System Use Cases (UC-S##), and Supplementary Specs. Structure-only, no historical background. Also registers the new workflow in the visualizer workflow list. --- .beads/issues.jsonl | 30 + .beads/last-touched | 2 +- ...socratic-architecture-recovery-workflow.md | 249 ++++++++ .../visualizer/src/services/workflow-list.ts | 1 + .../requirements/cockburn-use-cases.md | 151 +++++ resources/workflows/socratic-recovery.yaml | 588 ++++++++++++++++++ 6 files changed, 1020 insertions(+), 1 deletion(-) create mode 100644 .vibe/development-plan-feat-socratic-architecture-recovery-workflow.md create mode 100644 resources/templates/requirements/cockburn-use-cases.md create mode 100644 resources/workflows/socratic-recovery.yaml diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index e8000729..d3a7e0a4 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -362,6 +362,36 @@ {"id":"responsible-vibe-34.3.2","title":"Run pnpm install to update lock file","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-05-07T17:50:35.968498+02:00","created_by":"Oliver Jägle","updated_at":"2026-05-07T17:51:12.461356+02:00","closed_at":"2026-05-07T17:51:12.461356+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-34.3.2","depends_on_id":"responsible-vibe-34.3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-34.3.3","title":"Build and verify no TypeScript errors","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-05-07T17:50:36.175905+02:00","created_by":"Oliver Jägle","updated_at":"2026-05-07T17:51:19.586457+02:00","closed_at":"2026-05-07T17:51:19.586457+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-34.3.3","depends_on_id":"responsible-vibe-34.3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-34.4","title":"Commit","description":"Ensure code quality and documentation accuracy through systematic cleanup and review. **STEP 1: Code Cleanup** Systematically clean up development artifacts: 1. **Remove Debug Output**: Search for and remove all temporary debug output statements used during development. Look for language-specific debug output methods (console logging, print statements, debug output functions). Remove any debugging statements that were added for development purposes. 2. **Review TODO/FIXME Comments**: - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred - Remove completed TODOs - Convert remaining TODOs to proper issue tracking if needed 3. **Remove Debugging Code Blocks**: - Remove temporary debugging code, test code blocks, and commented-out code - Clean up any experimental code that's no longer needed - Ensure proper error handling replaces temporary debug logging **STEP 2: Documentation Review** Review and update documentation to reflect final implementation: 1. **Update Long-Term Memory Documents**: Based on what was actually implemented: - If exists: Update it if requirements changed during development - If exists: Update it if architectural impacts were identified - If exists: Update it if design details were refined or changed - Otherwise: Document any changes in the plan file 2. **Compare Against Implementation**: Review documentation against actual implemented functionality 3. **Update Changed Sections**: Only modify documentation sections that have functional changes 4. **Remove Development Progress**: Remove references to development iterations, progress notes, and temporary decisions 5. **Focus on Final State**: Ensure documentation describes the final implemented state, not the development process 6. **Ask User to Review Document Updates** **STEP 3: Final Validation** - Run existing tests to ensure cleanup didn't break functionality - Verify documentation accuracy with a final review - Ensure code is ready for production/delivery Update task progress and mark completed work as you finalize the feature.","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-05-07T17:29:25.065441+02:00","created_by":"Oliver Jägle","updated_at":"2026-05-07T17:29:25.065441+02:00","dependencies":[{"issue_id":"responsible-vibe-34.4","depends_on_id":"responsible-vibe-34","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-34.4","depends_on_id":"responsible-vibe-34.3","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35","title":"workflows: epcc (development-plan-feat-socratic-architecture-recovery-workflow.md)","description":"Responsible vibe engineering session using epcc workflow for workflows","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:53:52.801594+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:53:52.801594+02:00"} +{"id":"responsible-vibe-35.1","title":"Explore","description":"Figure out the INTENT of the users instructions. Research the codebase to understand existing patterns and gather context about the problem space. - If uncertain about conventions or rules, ask the user about them - Read relevant files and documentation - If exists: Understand and document requirements there - Otherwise: Document requirements in your task management system Focus on understanding without writing code yet. Document your findings and create tasks as needed.","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:53:52.971997+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:53:52.971997+02:00","dependencies":[{"issue_id":"responsible-vibe-35.1","depends_on_id":"responsible-vibe-35","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.1.1","title":"Read blog post \u0026 understand Socratic Recovery method","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:54:57.187265+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:55:00.963682+02:00","closed_at":"2026-06-15T12:55:00.963682+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.1.1","depends_on_id":"responsible-vibe-35.1","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.1.2","title":"Analyze c4-analysis.yaml as reference pattern","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:54:57.34399+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:55:01.088642+02:00","closed_at":"2026-06-15T12:55:01.088642+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.1.2","depends_on_id":"responsible-vibe-35.1","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.1.3","title":"Define phases \u0026 states for new workflow","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:54:57.511052+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:55:01.212829+02:00","closed_at":"2026-06-15T12:55:01.212829+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.1.3","depends_on_id":"responsible-vibe-35.1","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.1.4","title":"Document key decisions in plan file","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:54:57.669089+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:55:01.33695+02:00","closed_at":"2026-06-15T12:55:01.33695+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.1.4","depends_on_id":"responsible-vibe-35.1","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2","title":"Plan","description":"Create a detailed implementation strategy based on your exploration: - If exists: Base your strategy on requirements from it - Otherwise: Use existing task context Break down the work into specific, actionable tasks. Consider edge cases, dependencies, and potential challenges. - If architectural changes needed and exists: Document in - Otherwise: Create tasks to track architectural decisions - If exists: Adhere to the design in it - Otherwise: Elaborate design options and present them to the user Document the planning work thoroughly and create implementation tasks as part of the code phase as needed.","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:53:53.136566+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:53:53.136566+02:00","dependencies":[{"issue_id":"responsible-vibe-35.2","depends_on_id":"responsible-vibe-35","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-35.2","depends_on_id":"responsible-vibe-35.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.1","title":"Design state-by-state YAML structure for socratic-recovery.yaml","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:27:39.219452+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T13:27:42.73998+02:00","closed_at":"2026-06-15T13:27:42.73998+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.1","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.10","title":"Remove self-transitions from state design","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:40:39.262071+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:08:47.62166+02:00","closed_at":"2026-06-16T07:08:47.62166+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.10","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.2","title":"Write full default_instructions for question_tree state","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:27:39.44111+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T13:27:56.060171+02:00","closed_at":"2026-06-15T13:27:56.060171+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.2","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.3","title":"Write full default_instructions for answer_open_questions state","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:27:39.601764+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T13:27:56.185792+02:00","closed_at":"2026-06-15T13:27:56.185792+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.3","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.4","title":"Write full default_instructions for synthesize_documentation state","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:27:39.758167+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T13:27:56.357677+02:00","closed_at":"2026-06-15T13:27:56.357677+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.4","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.5","title":"Write full default_instructions for review_and_rework state","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:27:39.911958+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T13:27:56.486946+02:00","closed_at":"2026-06-15T13:27:56.486946+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.5","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.6","title":"Define all transitions and triggers with review_perspectives","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:27:40.06725+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T13:27:56.631696+02:00","closed_at":"2026-06-15T13:27:56.631696+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.6","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.7","title":"Update plan file with final state design and proceed to code phase","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:27:40.215539+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T13:28:55.013641+02:00","closed_at":"2026-06-15T13:28:55.013641+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.7","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.8","title":"Resolve Q2 adoc-vs-md format decision and update plan","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:40:38.943336+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:08:47.37079+02:00","closed_at":"2026-06-16T07:08:47.37079+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.8","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.2.9","title":"Decide on Cockburn use-case requirements template","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T13:40:39.103126+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:08:47.49776+02:00","closed_at":"2026-06-16T07:08:47.49776+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.2.9","depends_on_id":"responsible-vibe-35.2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.3","title":"Code","description":"Follow your plan to build the solution: - If exists: Follow the design from it - Otherwise: Elaborate design options and present them to the user - If exists: Build according to the architecture from it - Otherwise: Elaborate architectural options and present them to the user - If exists: Ensure requirements from it are met - Otherwise: Ensure existing requirements are met based on your task context Write clean, well-structured code with proper error handling. Prevent regression by building, linting, and executing existing tests. Stay flexible and adapt the plan as you learn more during implementation. Update task progress and create new tasks as needed.","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:53:53.30483+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:53:53.30483+02:00","dependencies":[{"issue_id":"responsible-vibe-35.3","depends_on_id":"responsible-vibe-35","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-35.3","depends_on_id":"responsible-vibe-35.2","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.3.1","title":"Write cockburn-use-cases.md template","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:10:55.946685+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:12:27.584466+02:00","closed_at":"2026-06-16T07:12:27.584466+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.3.1","depends_on_id":"responsible-vibe-35.3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.3.2","title":"Write socratic-recovery.yaml workflow","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:10:56.117919+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:05.197812+02:00","closed_at":"2026-06-16T07:15:05.197812+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.3.2","depends_on_id":"responsible-vibe-35.3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.3.3","title":"Validate YAML against schema","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:10:56.273247+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:16:33.479893+02:00","closed_at":"2026-06-16T07:16:33.479893+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.3.3","depends_on_id":"responsible-vibe-35.3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4","title":"Commit","description":"Ensure code quality and documentation accuracy through systematic cleanup and review. **STEP 1: Code Cleanup** Systematically clean up development artifacts: 1. **Remove Debug Output**: Search for and remove all temporary debug output statements used during development. Look for language-specific debug output methods (console logging, print statements, debug output functions). Remove any debugging statements that were added for development purposes. 2. **Review TODO/FIXME Comments**: - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred - Remove completed TODOs - Convert remaining TODOs to proper issue tracking if needed 3. **Remove Debugging Code Blocks**: - Remove temporary debugging code, test code blocks, and commented-out code - Clean up any experimental code that's no longer needed - Ensure proper error handling replaces temporary debug logging **STEP 2: Documentation Review** Review and update documentation to reflect final implementation: 1. **Update Long-Term Memory Documents**: Based on what was actually implemented: - If exists: Update it if requirements changed during development - If exists: Update it if architectural impacts were identified - If exists: Update it if design details were refined or changed - Otherwise: Document any changes in the plan file 2. **Compare Against Implementation**: Review documentation against actual implemented functionality 3. **Update Changed Sections**: Only modify documentation sections that have functional changes 4. **Remove Development Progress**: Remove references to development iterations, progress notes, and temporary decisions 5. **Focus on Final State**: Ensure documentation describes the final implemented state, not the development process 6. **Ask User to Review Document Updates** **STEP 3: Final Validation** - Run existing tests to ensure cleanup didn't break functionality - Verify documentation accuracy with a final review - Ensure code is ready for production/delivery Update task progress and mark completed work as you finalize the feature. ","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:53:53.480495+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:53:53.480495+02:00","dependencies":[{"issue_id":"responsible-vibe-35.4","depends_on_id":"responsible-vibe-35","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-35.4","depends_on_id":"responsible-vibe-35.3","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.1","title":"Code cleanup: scan for debug/TODO artifacts in both new files","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.336567+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:21:56.914068+02:00","closed_at":"2026-06-16T07:21:56.914068+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.1","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.2","title":"Documentation review: check plan file completeness and update if needed","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.493699+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:22:28.679886+02:00","closed_at":"2026-06-16T07:22:28.679886+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.2","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.3","title":"Final validation: run full test suite","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.64241+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:23:33.765583+02:00","closed_at":"2026-06-16T07:23:33.765583+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.3","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.4","title":"Create PR","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.791302+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:21:46.791302+02:00","dependencies":[{"issue_id":"responsible-vibe-35.4.4","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-36","title":"workflows: minor (development-plan-feat-socratic-architecture-recovery-workflow.md)","description":"Create a new workflow YAML file () that guides an LLM through the **Socratic Code-Theory Recovery** method described in Ralf Müller's blog post. This workflow is the successor/complement to for retrospective/brownfield engineering. Instead of C4-based analysis, it uses arc42 as the documentation target, and uniquely produces an **OPEN_QUESTIONS list** (the more valuable artifact) alongside architecture docs.","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:52.947814+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:52.947814+02:00"} +{"id":"responsible-vibe-36.1","title":"Explore","description":"Understand the problem, analyze existing patterns, and design your approach. Consider the scope and impact of the change. **STEP 1: Analyze Requirements** - If exists: Use it to understand the required changes - Otherwise: Document requirements in your task management system **STEP 2: Review Design Approach** - If exists: Respect the design approach documented in - Otherwise: Design your approach based on the problem analysis **STEP 3: Document Decisions** - Document your analysis and design decisions - Create tasks to guide implementation - Focus on analysis and design only - do not write any code yet","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:53.112518+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:53.112518+02:00","dependencies":[{"issue_id":"responsible-vibe-36.1","depends_on_id":"responsible-vibe-36","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-36.2","title":"Implement","description":"Write clean, focused code for the minor enhancement, test your changes, and prepare for commit. **STEP 1: Review Design and Requirements** - If exists: Follow your design from - Otherwise: Elaborate design options and present them to the user - If exists: Ensure the relevant requirements from are met - Otherwise: Ensure existing requirements are met based on your task context **STEP 2: Implement Changes** - Write clean, focused code for the minor enhancement - Test your changes to ensure they work correctly and don't break existing functionality **STEP 3: Prepare for Finalization** - Update task progress as needed - Prepare documentation and commit when ready","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:53.272944+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:53.272944+02:00","dependencies":[{"issue_id":"responsible-vibe-36.2","depends_on_id":"responsible-vibe-36","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-36.2","depends_on_id":"responsible-vibe-36.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-36.3","title":"Finalize","description":"Ensure code quality and documentation accuracy through systematic cleanup and review. **STEP 1: Code Cleanup** Systematically clean up development artifacts: - **Remove Debug Output**: Search for and remove all temporary debug output statements used during development. Look for language-specific debug output methods (console logging, print statements, debug output functions). Remove any debugging statements that were added for development purposes. - **Review TODO/FIXME Comments**: - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred - Remove completed TODOs - Convert remaining TODOs to proper issue tracking if needed - **Remove Debugging Code Blocks**: - Remove temporary debugging code, test code blocks, and commented-out code - Clean up any experimental code that's no longer needed - Ensure proper error handling replaces temporary debug logging **STEP 2: Documentation Review** Review and update documentation to reflect final implementation: - **Update Long-Term Memory Documents**: Based on what was actually implemented: - If exists: Update if requirements changed during development - If exists: Update if design details were refined or changed - **Compare Against Implementation**: Review documentation against actual implemented functionality - **Update Changed Sections**: Only modify documentation sections that have functional changes - **Remove Development Progress**: Remove references to development iterations, progress notes, and temporary decisions - **Focus on Final State**: Ensure documentation describes the final implemented state, not the development process - **Ask User to Review Document Updates** **STEP 3: Final Validation** - Run existing tests to ensure cleanup didn't break functionality - Verify documentation accuracy with a final review - Ensure minor enhancement is ready for delivery - Update task progress and mark completed work as you finalize the minor enhancement ","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:53.644168+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:53.644168+02:00","dependencies":[{"issue_id":"responsible-vibe-36.3","depends_on_id":"responsible-vibe-36","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-36.3","depends_on_id":"responsible-vibe-36.2","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-4","title":"Responsible-Vibe Development: responsible-vibe","description":"Development session using minor workflow for responsible-vibe","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-01-20T08:45:26.033247+01:00","created_by":"Oliver Jägle","updated_at":"2026-01-20T08:45:26.033247+01:00"} {"id":"responsible-vibe-4.1","title":"Explore","description":"minor workflow explore phase tasks","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-01-20T08:45:26.241377+01:00","created_by":"Oliver Jägle","updated_at":"2026-01-20T08:45:26.241377+01:00","dependencies":[{"issue_id":"responsible-vibe-4.1","depends_on_id":"responsible-vibe-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-4.1.1","title":"Analyze current verbose task management sections in plan file templates","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-01-20T08:46:16.960883+01:00","created_by":"Oliver Jägle","updated_at":"2026-01-20T08:46:58.154323+01:00","closed_at":"2026-01-20T08:46:58.154323+01:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-4.1.1","depends_on_id":"responsible-vibe-4.1","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} diff --git a/.beads/last-touched b/.beads/last-touched index fda1d612..5cb1a906 100644 --- a/.beads/last-touched +++ b/.beads/last-touched @@ -1 +1 @@ -responsible-vibe-34.3.3 +responsible-vibe-35.4.4 diff --git a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md new file mode 100644 index 00000000..47fdd1a0 --- /dev/null +++ b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md @@ -0,0 +1,249 @@ +# Development Plan: workflows (feat/socratic-architecture-recovery-workflow branch) + +*Generated on 2026-06-15 by Vibe Feature MCP* +*Workflow: [epcc](https://codemcp.github.io/workflows/workflows/epcc)* + +## Goal +Create a new workflow YAML file (`socratic-recovery.yaml`) that guides an LLM through the **Socratic Code-Theory Recovery** method described in Ralf Müller's blog post. This workflow is the successor/complement to `c4-analysis.yaml` for retrospective/brownfield engineering. Instead of C4-based analysis, it uses arc42 as the documentation target, and uniquely produces an **OPEN_QUESTIONS list** (the more valuable artifact) alongside architecture docs. + +## Key Decisions +- **Workflow filename**: `socratic-recovery.yaml` +- **Domain**: `architecture` (same as `c4-analysis.yaml`) +- **Complexity**: `high` (multi-phase, human gates, independent review phases) +- **Follows existing schema**: Uses `name`, `description`, `initial_state`, `states`, `metadata` with same YAML structure as `c4-analysis.yaml` +- **NO docToolchain needed**: The arc42 template is already shipped as `resources/templates/architecture/arc42/arc42-template-EN.md` — use `setup_project_docs({ architecture: "arc42" })` instead +- **NO plugin installation needed**: The Semantic Anchors "plugin" is just prompts (a `SKILL.md` + `prompts/` folder). The LLM already knows the methodology. The workflow instructions embed the method directly — no installation step required. +- **Output files are context-namespaced** (SKILL.md v0.3 behaviour): `QUESTION_TREE-.adoc` and `OPEN_QUESTIONS-.adoc` — no overwrite footgun for multiple bounded contexts +- **4 workflow states** (setup collapsed into question_tree since no tooling installation is needed): + 1. `question_tree` – Set up arc42 doc skeleton via `setup_project_docs`, then run Phase 1 (5 root questions × fixed second level × adaptive depth) → produces `QUESTION_TREE-.adoc` + `OPEN_QUESTIONS-.adoc` + 2. `answer_open_questions` – Human routes OPEN leaves to roles (PO, Architect, Developer, Domain Expert, Ops), answers or explicitly defers each one. Gate: every leaf must have an answer OR `(deferred)` marker before Phase 2. + 3. `synthesize_documentation` – Run Phase 2: produces PRD (Q1), Cockburn use-case spec (Q2), arc42 12 chapters (Q3), Nygard ADRs (Q3.9). Code claims cite `file:line`; team input marked `(team answer)`. Gaps remain visible, not invented. + 4. `review_and_rework` – Independent session: Fagan Inspection → Traceability Check → ATAM (provisional if Q4.9 deferred). Fix defects only; leave gaps as gaps. +- **Key insight to encode**: The OPEN_QUESTIONS list is the PRIMARY deliverable. Gaps must NEVER be filled by invention — a deferred leaf is honest; an invented answer is the failure mode. +- **Distinction from c4-analysis**: c4-analysis = manual code reading → C4 diagrams. Socratic recovery = structured question tree → arc42 + explicit gap list. +- **Healthy OPEN leaf range**: 10–15. More → split the bounded context. Far fewer → check the bounded context wasn't too narrow. + +## Notes +- Blog post: https://rdmueller.github.io/pages/blog/socratic-recovery-tutorial.html +- Semantic Anchors SKILL.md + prompts fully read: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/plugins/semantic-anchors/skills/socratic-code-theory-recovery/ +- arc42 template already at: `resources/templates/architecture/arc42/arc42-template-EN.md` +- Phase 1 fixed second-level nodes: Q1.1–Q1.6 (product), Q2.1–Q2.6 (Cockburn use cases), Q3.1–Q3.12 (arc42 chapters), Q4.1–Q4.9 (ISO 25010 + priority), Q5.1–Q5.5 (risks/debt) +- Q3.2 also has a fixed third level: Q3.2.1 technical, Q3.2.2 org/process, Q3.2.3 conventional constraints +- Phase 2 output paths (from prompt): `docs/specs/prd-[name].adoc`, `docs/specs/use-cases-[name].adoc`, `docs/arc42/arc42-[name].adoc`, `docs/specs/adrs/[name]-adr-NNN-*.adoc` +- The Phase 1 and Phase 2 prompts are complete self-contained blocks — embed them verbatim in state instructions (substituting path/context-name) +- Post-Phase-2 step: Fagan Inspection, Traceability Check, ATAM — all in a FRESH session on a different model ideally; all write to `docs/reports/` +- `$DONE_DEFAULT` macro available for terminal states (seen in c4-analysis.yaml) +- Schema requires per-state: `description`, `default_instructions`, `transitions` (each needs `trigger`, `to`, `transition_reason`) +- Optional per-transition: `instructions`, `additional_instructions`, `review_perspectives` +- Optional per-state: `allowed_file_patterns` + +## Explore + +### Tasks + +*Auto-synced — do not edit here, use `bd` CLI instead.* + +- [x] `responsible-vibe-35.1.1` Read blog post & understand Socratic Recovery method +- [x] `responsible-vibe-35.1.2` Analyze c4-analysis.yaml as reference pattern +- [x] `responsible-vibe-35.1.3` Define phases & states for new workflow +- [x] `responsible-vibe-35.1.4` Document key decisions in plan file + +## Plan + +### Tasks + +*Auto-synced — do not edit here, use `bd` CLI instead.* + +- [x] `responsible-vibe-35.2.1` Design state-by-state YAML structure for socratic-recovery.yaml +- [x] `responsible-vibe-35.2.10` Remove self-transitions from state design +- [x] `responsible-vibe-35.2.2` Write full default_instructions for question_tree state +- [x] `responsible-vibe-35.2.3` Write full default_instructions for answer_open_questions state +- [x] `responsible-vibe-35.2.4` Write full default_instructions for synthesize_documentation state +- [x] `responsible-vibe-35.2.5` Write full default_instructions for review_and_rework state +- [x] `responsible-vibe-35.2.6` Define all transitions and triggers with review_perspectives +- [x] `responsible-vibe-35.2.7` Update plan file with final state design and proceed to code phase +- [x] `responsible-vibe-35.2.8` Resolve Q2 adoc-vs-md format decision and update plan +- [x] `responsible-vibe-35.2.9` Decide on Cockburn use-case requirements template + +### State-by-State Design + +#### State 1: `question_tree` (initial state) + +**Description**: Set up arc42 documentation skeleton and run Phase 1 Socratic Code-Theory Recovery — builds QUESTION_TREE and OPEN_QUESTIONS files for a named bounded context. + +**allowed_file_patterns**: `["docs/**/*.adoc", "QUESTION_TREE-*.adoc", "OPEN_QUESTIONS-*.adoc"]` + +**default_instructions** (summary — full content in YAML): +1. Ask for bounded context (path + short name) if not already given — NEVER run against CWD by default +2. Set up arc42 doc skeleton: `setup_project_docs({ architecture: "arc42", requirements: "none", design: "none" })` +3. Run Phase 1 prompt verbatim (substituting `[bounded context path]` and `[context-name]`) +4. Write `QUESTION_TREE-.adoc` and `OPEN_QUESTIONS-.adoc` +5. Sanity-check: pick 3 `[ANSWERED]` leaves, verify the cited file:line is real; check depth (no leaf backed by a directory) +6. Report healthy OPEN count guidance (10–15 healthy; >50 → context too large; <5 → check depth) +7. Stop — do NOT run Phase 2 + +**Transitions**: +- `refine_question_tree` → `question_tree`: Re-run/extend tree for a different branch or finer depth (self-loop) + - reason: "Phase 1 tree needs deeper decomposition or a second bounded context" +- `question_tree_complete` → `answer_open_questions`: Move OPEN_QUESTIONS to team for answering + - reason: "Phase 1 complete; OPEN_QUESTIONS file ready for team routing" + - additional_instructions: "Remind user to route `OPEN_QUESTIONS-.adoc` to appropriate roles (PO, Architect, Developer, Domain Expert, Operations) and to write answers/deferrals directly into the file before triggering `open_questions_answered`." + +--- + +#### State 2: `answer_open_questions` + +**Description**: Human-gated state — team routes OPEN leaves to the right roles, writes answers or explicit `(deferred)` markers directly in `OPEN_QUESTIONS-.adoc`. The LLM acts as a facilitator and gate-keeper; it does NOT fill in gaps. + +**allowed_file_patterns**: `["OPEN_QUESTIONS-*.adoc"]` + +**default_instructions** (summary): +1. Read current `OPEN_QUESTIONS-.adoc` +2. Check: does every `[OPEN]` leaf have either a team answer or `(deferred)` marker? + - If NO: list the unanswered leaves grouped by role; ask user to provide answers before proceeding + - If YES: confirm gate is met, suggest triggering `open_questions_answered` +3. Critical rule: NEVER invent answers. A deferred leaf is honest; an invented answer is the failure mode. + +**Transitions**: +- `continue_answering` → `answer_open_questions`: More questions to answer (self-loop) + - reason: "Team is still routing and answering OPEN leaves" +- `open_questions_answered` → `synthesize_documentation`: Gate passed — all leaves answered or deferred + - reason: "Every OPEN leaf has a team answer or (deferred) marker; Phase 2 can proceed" + - review_perspectives: Check that no answer looks fabricated (no "invented" content); verify all (deferred) markers are genuine team decisions, not evasions + +--- + +#### State 3: `synthesize_documentation` + +**Description**: Run Phase 2 — synthesize PRD, Cockburn use-case spec, arc42 (12 chapters), and Nygard ADRs from the answered Question Tree. Code-derived claims cite `file:line`; team answers marked `(team answer)`; deferred questions remain explicit gaps — NEVER filled by invention. + +**allowed_file_patterns**: `["docs/specs/prd-*.adoc", "docs/specs/use-cases-*.adoc", "docs/arc42/arc42-*.adoc", "docs/specs/adrs/*.adoc"]` + +**default_instructions** (summary): +1. Verify gate: re-check that every `[OPEN]` leaf in `OPEN_QUESTIONS-.adoc` has an answer or `(deferred)` marker — if not, stop and list unanswered leaves +2. Run Phase 2 prompt verbatim against `QUESTION_TREE-.adoc` + `OPEN_QUESTIONS-.adoc` +3. Produce exactly four artifacts: + - `docs/specs/prd-.adoc` (from Q1 branch) + - `docs/specs/use-cases-.adoc` (from Q2 branch) + - `docs/arc42/arc42-.adoc` (from Q3 branch, all 12 chapters) + - `docs/specs/adrs/-adr-NNN-*.adoc` (one ADR per Q3.9 decision, with Pugh Matrix) +4. Traceability rules: every claim traces to a leaf; Q-IDs NOT in output; code-derived claims cite file:line; team input marked `(team answer)`; deferred items stay as explicit gaps +5. arc42 Chapter 10 is an exception — always synthesize from Q4 answered scenarios + Q4.9 ranking (never `[OPEN]` pointer) + +**Transitions**: +- `refine_synthesis` → `synthesize_documentation`: Rework a specific artifact (self-loop) + - reason: "One or more artifacts need deeper content or formatting polish" +- `synthesis_complete` → `review_and_rework`: Documentation synthesized; ready for independent review + - reason: "All four Phase 2 artifacts produced; ready for Fagan Inspection + Traceability Check + ATAM" + - additional_instructions: "Remind user: the review MUST happen in a FRESH session (ideally a different model) to avoid confirmation bias. The review LLM should NOT have seen the synthesis session." + +--- + +#### State 4: `review_and_rework` + +**Description**: Independent review of the four synthesized documents — Fagan Inspection, Traceability Check, and ATAM. Must run in a FRESH session (different model ideally). Fix confirmed defects only; leave gaps as gaps. Write results to `docs/reports/`. + +**allowed_file_patterns**: `["docs/reports/*.adoc", "docs/specs/prd-*.adoc", "docs/specs/use-cases-*.adoc", "docs/arc42/arc42-*.adoc", "docs/specs/adrs/*.adoc"]` + +**default_instructions** (summary): +1. **Important**: This state should ideally run in a new, independent LLM session with no memory of the synthesis session — tell the user this before starting +2. Read the four artifacts: PRD, use-case spec, arc42, ADRs +3. Run three review passes in sequence: + - **Fagan Inspection**: check completeness, clarity, consistency, verifiability — log defects with severity (major/minor) to `docs/reports/fagan-inspection-.adoc` + - **Traceability Check**: verify every code-derived claim has a valid `file:line` citation; verify team answers are marked `(team answer)`; list any uncited claims as defects + - **ATAM**: evaluate whether the ADRs' Pugh Matrices actually address the Q4 quality goals; if Q4.9 (priority) was deferred, mark the ATAM as provisional — `docs/reports/atam-.adoc` +4. Fix confirmed defects (wrong content, missing citations) — fix means correction, not gap-filling +5. Leave `(deferred)` gaps as gaps — they are not defects +6. Summarize review results in `docs/reports/review-summary-.adoc` + +**Transitions**: +- `fix_defects` → `review_and_rework`: Apply fixes and re-review (self-loop) + - reason: "Defects found that need correction; re-review after fixing" +- `recovery_complete` → `recovery_done`: All defects resolved; documentation is ship-ready + - reason: "Review clean (or only deferred gaps remain); Socratic Recovery complete" + +--- + +#### State 5: `recovery_done` (terminal) + +**Description**: Socratic Code-Theory Recovery complete. Four documentation artifacts produced (PRD, spec, arc42, ADRs) plus review reports. OPEN_QUESTIONS file is the living gap register. + +**default_instructions**: +- Summary of deliverables with paths +- Remind about spec drift: re-run Phase 1 before each release and diff the new Question Tree +- Suggest next bounded context +- `$DONE_DEFAULT` + +**Transitions**: `[]` + +--- + +### Key Design Decisions (Plan Phase) + +- **No self-transitions**: The workflow is strictly sequential (Phase 1 → team gate → Phase 2 → review). No self-loop transitions needed. Users iterate naturally within a state without a trigger. +- **All output files use `.md` (not `.adoc`)**: Normalizing to Markdown throughout. Local arc42 template is already `.md`; `setup_project_docs` creates `.md` files; users are unlikely to have AsciiDoc tooling. The Semantic Anchors prompts say "AsciiDoc" but that is cosmetic — the methodology is fully preserved in Markdown. QUESTION_TREE and OPEN_QUESTIONS are intermediate working files → `.md`. +- **YAML block scalar style**: Use `>` (folded) for long default_instructions strings (same as c4-analysis.yaml). Use `|` (literal) only for `additional_instructions` blocks that embed code/lists that need hard line breaks. +- **Phase 1 prompt embedding**: Embed verbatim inside a fenced code block within the `default_instructions` string — the fences are part of the instructions (LLM reads them as the prompt to copy). Substitute `[bounded context path]` and `[context-name]` as user-provided substitution hints in surrounding text. +- **Phase 2 prompt embedding**: Same pattern — verbatim block, substitution hints in surrounding text. +- **Gate enforcement in YAML**: The gate check (every OPEN leaf answered) is encoded in the `default_instructions` of both `answer_open_questions` (the human step) and `synthesize_documentation` (the LLM double-checks before running Phase 2). Belt-and-suspenders. +- **`review_perspectives` on `open_questions_answered` transition**: Check that no answer looks fabricated — catches the "team answer that's really invention" failure mode. +- **No `$DISCOVERY_FILE` variable**: Unlike c4-analysis, Socratic Recovery's memory lives in the two `.md` output files by design. No separate discovery note file needed. +- **`requiresDocumentation: false`**: arc42 template is set up inside `question_tree` state itself (via `setup_project_docs`), not as a workflow precondition. +- **New template file to ship**: `resources/templates/requirements/cockburn-use-cases.md` — lean structural template, no historical background section (agents already know Cockburn; include structure + minimal inline instructions only). +- **`setup_project_docs` call**: `setup_project_docs({ architecture: "arc42", requirements: "cockburn-use-cases", design: "none" })` + +### Cockburn Use-Cases Template Design + +**File**: `resources/templates/requirements/cockburn-use-cases.md` + +**Background / Evolution of Use Cases**: +- **1987**: Ivar Jacobson introduced use cases at OOPSLA'87 (Ericsson). Original term: *användningsfall* (Swedish). First systematic treatment of interaction-based requirements. +- **1992**: Jacobson's *OOSE* book popularized use cases for OO analysis; established the use-case-driven approach. +- **1995**: Larry Constantine introduced *essential use cases* — abstract, UI-free descriptions of user intent (for UCD). +- **1997**: UML standardized use case diagrams (OMG). Jacobson, Booch, Rumbaugh co-authored UML. +- **1999**: Unified Process (UP/RUP) promoted use-case-driven development lifecycle. +- **2000**: Alistair Cockburn published *Writing Effective Use Cases* — the canonical text on goal-oriented, fully-dressed use cases. Introduced goal levels (cloud/kite/sea-level/fish/clam) and the fully dressed template. +- **2001–2002**: Bittner & Spence extended the practice; Martin Fowler described a simpler "Fowler style" (title + main success scenario + extensions) — essentially a use case at minimal precision. +- **Cockburn's own framing**: "A user story is a use case at 2 bits of precision. Bits 3–6 add failure conditions, actions, data, and model." +- **2011**: Jacobson, Spence & Bittner published *Use Case 2.0* — adapted for agile with *use case slices* (thin vertical increments through a use case for Sprint planning). +- **Today**: The Cockburn Fully Dressed format remains the gold standard for capturing complex, non-trivial interactions. User stories cover bits 1–2; Cockburn covers bits 3–6. + +**Template structure decisions**: +1. Header comment block explaining the evolution + when to use Fully Dressed vs Casual vs user story +2. Two sections in the template: **Persona Use Cases** (user-goal level, Fully Dressed) + **System Use Cases** (per technical interface, leaner) +3. Each section has an inline filled example + a blank template to copy +4. Goal-level annotation (Cockburn's sea-level `!`, fish `-`, cloud `+`) in the title line +5. Comments on each field explaining *what to write* and *common mistakes* (e.g. "don't name UI controls in trigger", "stakeholder interests often OPEN") +6. Minimal Guarantees + Success Guarantees distinction (Cockburn's key insight: minimal = what holds even on failure) +7. Extensions numbered from the step they branch from (3a, 3b, not just "error handling") +8. Gherkin acceptance criteria as optional annex to each use case (links to EARS-style testability) + +## Code + +### Tasks + +*Auto-synced — do not edit here, use `bd` CLI instead.* + +- [x] `responsible-vibe-35.3.1` Write cockburn-use-cases.md template +- [x] `responsible-vibe-35.3.2` Write socratic-recovery.yaml workflow +- [x] `responsible-vibe-35.3.3` Validate YAML against schema + +## Commit + +### Tasks + +*Auto-synced — do not edit here, use `bd` CLI instead.* + +- [x] `responsible-vibe-35.4.1` Code cleanup: scan for debug/TODO artifacts in both new files — **none found** +- [x] `responsible-vibe-35.4.2` Documentation review: plan file updated (35.3.3 synced, .md decision confirmed) +- [ ] `responsible-vibe-35.4.3` Final validation: run full test suite +- [ ] `responsible-vibe-35.4.4` Create PR + +### Key Implementation Facts (final state) + +- `resources/workflows/socratic-recovery.yaml`: 5 states, 589 lines, schema-valid +- `resources/templates/requirements/cockburn-use-cases.md`: 149 lines, lean structure-only template +- All output paths use `.md` (not `.adoc` as in original blog post prompts — normalised throughout) +- No debug artifacts, no TODOs, no commented-out code in either file +- Integration tests pass (`test/integration/workflow-configuration.test.ts`) + diff --git a/packages/visualizer/src/services/workflow-list.ts b/packages/visualizer/src/services/workflow-list.ts index 86a434a7..d53be844 100644 --- a/packages/visualizer/src/services/workflow-list.ts +++ b/packages/visualizer/src/services/workflow-list.ts @@ -23,6 +23,7 @@ export const workflowList = [ 'skilled-epcc', 'skilled-greenfield', 'slides', + 'socratic-recovery', 'tdd', 'waterfall', ]; diff --git a/resources/templates/requirements/cockburn-use-cases.md b/resources/templates/requirements/cockburn-use-cases.md new file mode 100644 index 00000000..d07fb7ad --- /dev/null +++ b/resources/templates/requirements/cockburn-use-cases.md @@ -0,0 +1,151 @@ + + +# Use-Case Specification: [System / Bounded Context Name] + +--- + +## 1. Persona Use Cases + + + +### UC-P01 [!] [Imperative Verb Phrase] (Primary Actor: [Role]) + +| Field | Value | +| ---------------------------- | -------------------------------------------------------------------------------------- | +| **Scope** | [System under discussion] | +| **Primary Actor** | [Who initiates and has the goal] | +| **Stakeholders & Interests** | [Every affected party and what they want — list all, even if absent from the scenario] | + +**Preconditions** — what must be true before the use case starts + +- [State of system + actor] + +**Trigger** — the observable event that initiates this use case + +- [Actor intention, not a UI control] + +**Minimal Guarantee** — holds even on every failure path + +- [System invariant that is never violated, even on cancellation or error] + +**Success Guarantee** — additionally true on full success + +- [Observable outcome when the use case completes successfully] + +--- + +**Main Success Scenario** + +1. [Actor action] +2. [System response] +3. [Actor action] +4. [System produces main outcome] + +--- + +**Extensions** — branch from the step number they occur at (e.g. 3a, 3b) + +**3a.** [Condition at step 3]: + +1. [System or actor response] + +- Resume at step N | Use case ends (failure) | Use case ends (success) + +--- + +**Business Rules** + +- [BR-01: Rule reference or inline statement] + +--- + +**Gherkin Acceptance Criteria** _(optional)_ + +```gherkin +Scenario: [Happy path] + Given [precondition] + When [trigger] + Then [success outcome] + +Scenario: [Extension 3a] + Given [precondition] + When [condition] + Then [expected behaviour] +``` + +--- + +### UC-P02 [!] [Title] (Primary Actor: [Role]) + + + +--- + +## 2. System Use Cases + + + +### UC-S01 [Interface Identifier — e.g. POST /orders] + +| Field | Value | +| ---------------------- | ------------------------------------- | +| **Caller / Publisher** | [Who invokes this interface] | +| **Protocol / Format** | [REST/JSON, gRPC, CloudEvent, CSV, …] | + +**Input & Validation** + +| Parameter | Type | Required | Constraint | +| --------- | -------- | -------- | ----------------- | +| `[param]` | `[type]` | Yes/No | [verifiable rule] | + +**Processing** + +1. [What the system does with valid input] + +**Output / Response** + +| Condition | Status | Payload | +| --------- | ----------------- | -------------------- | +| Success | `200 OK` | [schema or example] | +| [Error] | `400 Bad Request` | `{ "error": "..." }` | + +--- + +### UC-S02 [Interface Identifier] + + + +--- + +## 3. Supplementary Specifications + +### 3.1 Entity Model + +| Entity | Key Attributes | Relationships | +| ---------- | -------------- | ------------------ | +| `[Entity]` | `id`, `[attr]` | has-many `[Other]` | + +### 3.2 State Machines + +**[Entity] lifecycle:** + +| From | Event | To | Guard | +| --------- | --------- | --------- | ---------- | +| `[State]` | `[event]` | `[State]` | [optional] | + +### 3.3 Cross-Cutting Contracts + +- **[Contract]**: [Applies to which use cases and what it mandates] + +### 3.4 Business Rules + +| ID | Description | Authority | +| ------- | ----------- | ------------------------------ | +| `BR-01` | [Rule] | [Law / policy / domain expert] | diff --git a/resources/workflows/socratic-recovery.yaml b/resources/workflows/socratic-recovery.yaml new file mode 100644 index 00000000..6f809d4a --- /dev/null +++ b/resources/workflows/socratic-recovery.yaml @@ -0,0 +1,588 @@ +# yaml-language-server: $schema=../state-machine-schema.json +--- +name: 'socratic-recovery' +description: >- + Brownfield architecture recovery using Socratic Code-Theory Recovery (Naur, 1985). + Builds a hierarchical Question Tree from source code, surfaces OPEN_QUESTIONS + for the team to answer, then synthesizes arc42 documentation, a PRD, Cockburn + use-case spec, and Nygard ADRs — with an independent Fagan/ATAM review pass. + The OPEN_QUESTIONS file is the primary deliverable: gaps are never invented. +initial_state: 'question_tree' +metadata: + domain: 'architecture' + complexity: 'high' + requiresDocumentation: false + bestFor: + - 'Brownfield / legacy system documentation' + - 'Recovering lost architecture knowledge' + - 'Producing arc42 from an undocumented codebase' + - 'Making implicit design decisions explicit' + - 'Identifying knowledge gaps before a major refactor or handover' + useCases: + - 'Document a legacy service before migrating it to a new platform' + - 'Onboard a new architect by recovering the system theory' + - 'Prepare for an architecture review board with no existing docs' + - 'Surface OPEN questions before a bounded-context redesign' + examples: + - 'Recover arc42 for a legacy Java payment service before cloud migration' + - 'Produce a PRD + use-case spec for an inherited Node.js API with no docs' + - 'Build an OPEN_QUESTIONS register for a monolith before strangler-fig extraction' + +states: + question_tree: + description: >- + Set up arc42 + Cockburn use-case documentation skeleton, then run Phase 1 + Socratic Code-Theory Recovery. Builds QUESTION_TREE-.md and + OPEN_QUESTIONS-.md for a named bounded context. + allowed_file_patterns: + - 'docs/**/*.md' + - 'QUESTION_TREE-*.md' + - 'OPEN_QUESTIONS-*.md' + default_instructions: > + You are starting Phase 1 of Socratic Code-Theory Recovery on a brownfield + bounded context. + + **STEP 0 — Ask for the bounded context if not already provided.** + + Before doing anything else, confirm: + 1. The path to the bounded context (directory or set of directories). + NEVER default to CWD — always ask. + 2. A short kebab-case context name (e.g. `auth`, `order-service`, + `payment-gateway`). This name is used in every output file name so + that sequential runs on different contexts never overwrite each other. + + **STEP 1 — Set up documentation skeleton.** + + Call: + `setup_project_docs({ architecture: "arc42", requirements: "cockburn-use-cases", design: "none" })` + + This creates: + - An arc42 Markdown skeleton (12 chapters) in the docs/ tree. + - A Cockburn Fully Dressed use-case template in the docs/ tree. + + Read both created files so you understand their structure before + generating content. + + **STEP 2 — Run Phase 1: Build the Question Tree.** + + Copy the following prompt verbatim into your working context. Replace + `[bounded context path]` with the actual path the user provided and + `[context-name]` with the kebab-case name from STEP 0. + + ``` + 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 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. 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 + + One node carries a FIXED third level too: Q3.2 (Architecture + Constraints) always emits exactly these three sub-nodes, mirroring the + constraint kinds arc42 Chapter 2 distinguishes: + Q3.2.1 technical constraints — language, runtime, mandated + frameworks/libraries + Q3.2.2 organizational/process constraints — git workflow, branching, + release process, review rules + Q3.2.3 conventional constraints — naming, file layout, code-style + rules, commit conventions + For the Q3.2 branch specifically, look beyond source code: CLAUDE.md / + AGENTS.md, CONTRIBUTING files, CI workflow definitions, and + linter/formatter configs are valid evidence sources — cite them + file:line like any other evidence. Constraints of these kinds rarely + live in dense code, so a code-density-driven decomposition would walk + right past them. + + 3. Below the fixed second level, decompose ADAPTIVELY and code-driven. + A node is a leaf ONLY when its question can be answered with specific + `file:line` (or `file::function`) evidence, or definitively marked + [OPEN]. If the honest answer would still be coarse — a whole directory + as evidence, "the building blocks are these four packages", a single + paragraph standing in for an entire arc42 chapter — the node is NOT a + leaf yet. Decompose it further ("building blocks?" -> "building blocks + of the tool subsystem?" -> "...of the agent loop?") until every leaf + maps to one specific, citable piece of code. + + Tree depth therefore tracks code density: a small bounded context + yields a shallow tree, a large one a deep tree — you do not have to + guess the right bounded-context granularity up front. Backstop against + runaway recursion: do not decompose more than four levels below a fixed + node. If a leaf is still too coarse at that depth, mark it [OPEN] + (Category: business-context or design-rationale) and note that the + bounded context may be too large to recover in one pass. + + The fixed second level (Q1.1-Q5.5) is the SAME on every run, so the + skeleton stays diffable; only the depth below it is adaptive. 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: + + [ANSWERED] + - You found the answer in the code. + - Cite the evidence as : or ::. + - Be exact. No "see X for details." + - A directory or a bare folder path is NOT valid evidence. If the + only honest cite is a directory, the leaf still covers too much — + go back to step 3 and decompose it further. + + [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. + + Quality (the Q4 branch) is not wholly team knowledge. Where the code + shows measurable behaviour — a timeout, a truncation limit, a budget, + a retry policy, the threats and test concept from Q3.8 — write it as + an [ANSWERED] quality scenario with file:line. Never invent a target + number. Only the quality-goal ranking (Q4.9) is [OPEN]. + + 5. Output two files in Markdown, named after the bounded context so that + sequential runs on different contexts never overwrite each other: + + QUESTION_TREE-[context-name].md + - 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-[context-name].md + - Only the [OPEN] leaves, copied verbatim from the Question Tree file + - 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 + the answered tree into PRD, specification, arc42, and ADRs — only after the + team has filled in the [OPEN] leaves. + ``` + + **STEP 3 — Sanity-check the output.** + + After writing both files: + 1. Pick three `[ANSWERED]` leaves at random. Verify each cited `file:line` + actually contains the claimed fact. If any citation is fabricated, + the bounded context is too large — stop and tell the user to narrow + the scope and re-run. + 2. Scan for `[ANSWERED]` leaves whose evidence is a directory path or a + whole file, or whose answer summarises an entire arc42 chapter in one + paragraph. Those leaves need further decomposition — the tree stopped + too early. + 3. Count the `[OPEN]` leaves: + - 10–15: healthy for a small bounded context. + - 15–30: acceptable for a larger one. + - > 50: the bounded context is too large; split it and re-run Phase 1 + on each half before proceeding. + - < 5: check whether decomposition depth was sufficient. + + **STOP HERE.** Do NOT run Phase 2 in this state. Phase 2 begins only after + the team has answered or deferred every `[OPEN]` leaf. + + transitions: + - trigger: 'question_tree_complete' + to: 'answer_open_questions' + transition_reason: >- + Phase 1 complete. QUESTION_TREE and OPEN_QUESTIONS files written, + sanity-checked, and ready for team routing. + additional_instructions: | + Remind the user: + + 1. Open `OPEN_QUESTIONS-.md`. + 2. Route each section to the appropriate role: + - **Product Owner** — Q1 / business context questions + - **Architect** — Q3 / design-rationale questions + - **Developer** — Q3 / implementation questions + - **Domain Expert** — Q1–Q2 / domain knowledge questions + - **Operations** — Q5 / operational / deployment questions + 3. Each person writes their answer **directly under the question**, + in plain prose (1–3 sentences is enough). + 4. If a question cannot be answered now, mark it explicitly as + `(deferred)` — do NOT leave it blank. + 5. When every question has an answer or `(deferred)`, trigger + `open_questions_answered`. + + answer_open_questions: + description: >- + Human-gated state. The team routes OPEN leaves to the right roles and + writes answers or explicit (deferred) markers directly in + OPEN_QUESTIONS-.md. The LLM acts as facilitator and + gate-keeper — it does NOT fill in gaps. + allowed_file_patterns: + - 'OPEN_QUESTIONS-*.md' + default_instructions: > + You are the gate-keeper for Phase 1 → Phase 2 hand-off. + + **CRITICAL RULE: You must NEVER invent answers to [OPEN] leaves.** + A deferred leaf is honest documentation. An invented answer is the + primary failure mode of this entire workflow — it produces documentation + that looks authoritative but is fabricated. If in doubt, mark as + (deferred). + + **STEP 1 — Read the current state of the file.** + + Read `OPEN_QUESTIONS-.md`. (Ask the user for the + context-name if it was not carried over from the previous state.) + + **STEP 2 — Check the gate condition.** + + Scan every `[OPEN]` leaf. For each one, check: + - Does it have a team answer written under it? (1–3 sentences of prose) + - Does it have an explicit `(deferred)` marker? + + If ANY leaf has neither: + - List all unanswered leaves grouped by Ask role. + - State clearly: "The following questions must be answered or explicitly + deferred before Phase 2 can run." + - Do NOT proceed. Wait for the user to provide answers. + + If ALL leaves are answered or deferred: + - Confirm: "Gate condition met — every [OPEN] leaf has a team answer + or (deferred) marker." + - Suggest triggering `open_questions_answered` to proceed to Phase 2. + + **STEP 3 — Assist with answering (optional).** + + If the user asks for help formulating a question to send to a stakeholder, + help them write a clear, concise question. Do NOT provide the answer + yourself unless you can derive it from the codebase with a `file:line` + citation. + + transitions: + - trigger: 'open_questions_answered' + to: 'synthesize_documentation' + transition_reason: >- + Every [OPEN] leaf has a team answer or (deferred) marker. + Phase 2 can now synthesize documentation from the answered tree. + review_perspectives: + - perspective: 'fabrication_check' + prompt: >- + Review every team answer in OPEN_QUESTIONS-.md. + Flag any answer that: + (a) Could only be known by reading source code (should be + [ANSWERED] with file:line, not a team answer); + (b) Is suspiciously precise without citing evidence (possible + hallucination or invention); + (c) Contradicts an [ANSWERED] leaf in the Question Tree. + Report findings before allowing the transition to proceed. + + synthesize_documentation: + description: >- + Run Phase 2 — synthesize PRD, Cockburn use-case spec, arc42 (12 chapters), + and Nygard ADRs from the answered Question Tree. Code-derived claims cite + file:line; team answers are marked (team answer); deferred questions remain + explicit gaps — never filled by invention. + allowed_file_patterns: + - 'docs/specs/prd-*.md' + - 'docs/specs/use-cases-*.md' + - 'docs/arc42/arc42-*.md' + - 'docs/specs/adrs/*.md' + default_instructions: > + You are running Phase 2 of Socratic Code-Theory Recovery. + + **STEP 0 — Re-verify the gate condition (belt-and-suspenders).** + + Read `OPEN_QUESTIONS-.md`. If ANY `[OPEN]` leaf has + neither a team answer nor an explicit `(deferred)` marker, STOP. + List the unanswered leaves and instruct the user to return to + `answer_open_questions`. + + **STEP 1 — Run Phase 2: Synthesize Documentation.** + + Copy the following prompt verbatim. Replace `[context-name]` with the + kebab-case context name used in Phase 1. + + ``` + You are performing Phase 2 of Socratic Code-Theory Recovery. + + Inputs: + - QUESTION_TREE-[context-name].md — the answered Question Tree from + Phase 1. + - OPEN_QUESTIONS-[context-name].md — same OPEN leaves, now with team + answers (or (deferred) markers) written under each question. + + Goal: synthesize documentation from the answered tree. Every claim must + trace back to a tree leaf — this is a build-time check, not a Q-ID stamped + into the text; Q-IDs do NOT appear in the final documents (see Rules for + traceability below). 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].md — Product Requirements Document + - Problem statement, target users, goals, success criteria, scope + boundaries, constraints, open questions + - Source: Q1 branch of QUESTION_TREE-[context-name].md + - Anchor: PRD (Cagan / Pichler) + + 2. docs/specs/use-cases-[context-name].md — 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-[context-name].md + - Anchor: Cockburn Use Cases + + 3. docs/arc42/arc42-[context-name].md — Architecture + - All 12 arc42 chapters. Mark chapters with no content as + "No information from Phase 1" rather than fabricating content. + - Chapter 10 (Quality Requirements) is an exception: synthesize it + from the [ANSWERED] Q4 quality scenarios plus the Q4.9 ranking. It + is never just an [OPEN] pointer. Reuse evidence already in Q3.8 — + Security scenarios cite the STRIDE T-IDs, Maintainability scenarios + the test concept. Only the goal ranking stays [OPEN]; "No + information" is legitimate here only if Q4 produced no answered + scenario at all. + - Source: Q3 branch of QUESTION_TREE-[context-name].md + - Anchor: arc42 (Starke / Hruschka) + + 4. docs/specs/adrs/[context-name]-adr-NNN-*.md — one ADR per + significant design decision. The context-name prefix keeps ADRs from + different bounded contexts from colliding in the shared adrs/ folder. + - 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-[context-name].md + - Anchor: ADR according to Nygard + + Rules for traceability: + - The synthesized documentation must be self-contained. The Question Tree + 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 + leaf — the reference to the code, the only durable, canonical artifact: + "The system uses Hexagonal Architecture [src/app/Ports.java, + src/adapter/JpaOrderRepository.java:30]." + Copy the Evidence line verbatim from the leaf; do not invent, shorten, + or re-derive file paths. A leaf with no Evidence line is not [ANSWERED] + and must not be cited as fact. + - Team-supplied facts have no code evidence — mark them (team answer): + "Sessions expire after 24 hours (team answer)." + - Deferred questions stay as explicit gaps: "Quality-goal priorities are + deferred and must be resolved before the next release." + - Do not introduce facts that do not appear in + QUESTION_TREE-[context-name].md or OPEN_QUESTIONS-[context-name].md. + If a section feels under-specified, leave it + under-specified — that is signal, not a defect. + ``` + + **STEP 2 — Verify the four artifacts.** + + After writing all four artifacts, confirm: + 1. `docs/specs/prd-.md` — problem, users, success criteria, scope. + 2. `docs/specs/use-cases-.md` — Cockburn Fully Dressed persona + use cases + system use cases per interface. + 3. `docs/arc42/arc42-.md` — all 12 chapters (gaps marked, + not invented; Chapter 10 synthesized from Q4 scenarios). + 4. `docs/specs/adrs/-adr-NNN-*.md` — one Nygard ADR with + Pugh Matrix per Q3.9 decision. + + Check that no Q-IDs appear in the output documents. Check that every + code-derived claim has a file:line citation. Check that deferred items + are labelled "(deferred)", not left blank or filled with speculation. + + transitions: + - trigger: 'synthesis_complete' + to: 'review_and_rework' + transition_reason: >- + All four Phase 2 artifacts produced and verified. Ready for + independent Fagan Inspection, Traceability Check, and ATAM. + additional_instructions: | + **IMPORTANT — Independent Review Session Required** + + The review in the next state MUST run in a FRESH LLM session with no + memory of this synthesis session. Confirmation bias is a real risk: + a model that wrote the documentation will miss its own errors. + + Ideally use a different model for the review session. At minimum, + start a brand-new conversation without any context from Phase 2. + + Hand the reviewer these files: + - `docs/specs/prd-.md` + - `docs/specs/use-cases-.md` + - `docs/arc42/arc42-.md` + - `docs/specs/adrs/-adr-NNN-*.md` + - `QUESTION_TREE-.md` (for traceability checking) + - `OPEN_QUESTIONS-.md` (for gap verification) + + review_and_rework: + description: >- + Independent review of the four synthesized documents — Fagan Inspection, + Traceability Check, and ATAM. Must run in a FRESH session (different model + ideally). Fix confirmed defects only; leave (deferred) gaps as gaps. + Review results written to docs/reports/. + allowed_file_patterns: + - 'docs/reports/*.md' + - 'docs/specs/prd-*.md' + - 'docs/specs/use-cases-*.md' + - 'docs/arc42/arc42-*.md' + - 'docs/specs/adrs/*.md' + default_instructions: > + You are performing an independent review of Socratic Recovery documentation. + + **IMPORTANT: This state should run in a new, independent LLM session.** + + If you have memory of writing the documents you are about to review, + STOP and tell the user: "I wrote these documents. Review in this session + would be biased. Please start a new session for the review, ideally with + a different model." Do not proceed with review in that case. + + **STEP 1 — Read the artifacts.** + + Read all six files: + - `docs/specs/prd-.md` + - `docs/specs/use-cases-.md` + - `docs/arc42/arc42-.md` + - `docs/specs/adrs/-adr-NNN-*.md` (all ADRs) + - `QUESTION_TREE-.md` (for traceability) + - `OPEN_QUESTIONS-.md` (for gap verification) + + **STEP 2 — Fagan Inspection.** + + Evaluate each document against: + - **Completeness**: Every required section present? Chapters marked + "No information" are acceptable; blank or missing chapters are defects. + - **Clarity**: Ambiguous statements? Undefined terms? + - **Consistency**: Do documents contradict each other? + - **Verifiability**: Are claims stated in a way that can be tested or + confirmed? + + Log each defect with: + - Document + section + - Severity: Major (blocks use of the document) or Minor (reduces quality) + - Description + + Write defects to `docs/reports/fagan-inspection-.md`. + + **STEP 3 — Traceability Check.** + + 1. For every code-derived claim in the four documents, verify the cited + `file:line` exists and contains the claimed fact. + 2. Verify all team-supplied facts are marked `(team answer)`. + 3. List any claims that are: + - Uncited (no `file:line` and no `(team answer)` marker) + - Wrongly cited (the cited location does not support the claim) + + Append traceability defects to `docs/reports/fagan-inspection-.md` + or write a separate `docs/reports/traceability-.md`. + + **STEP 4 — ATAM (Architecture Tradeoff Analysis).** + + 1. Read Chapter 10 (Quality Requirements) of `arc42-.md`. + 2. Read each ADR's Pugh Matrix. + 3. Evaluate: do the ADR trade-offs actually address the quality goals + in Chapter 10? + 4. If Q4.9 (quality-goal priority) was `(deferred)`, mark the ATAM as + **provisional** — the ranking is assumed, not confirmed. + + Write results to `docs/reports/atam-.md`. + + **STEP 5 — Fix confirmed defects.** + + - Fix defects that have wrong content or missing citations in the + source documents. + - Fixing means CORRECTING a wrong fact or adding a missing citation — + NOT filling in a gap with speculation. + - `(deferred)` gaps are NOT defects. Do not fill them. + + **STEP 6 — Write review summary.** + + Write `docs/reports/review-summary-.md` with: + - Total defects found (major / minor) + - Total defects fixed + - Remaining (deferred) gaps and their significance + - Overall quality assessment + - Recommended next steps + + transitions: + - trigger: 'fix_defects' + to: 'review_and_rework' + transition_reason: >- + Defects found in review. Applying fixes and re-reviewing the + affected documents. + + - trigger: 'recovery_complete' + to: 'recovery_done' + transition_reason: >- + Review clean — all defects resolved or confirmed as intentional gaps. + Socratic Recovery is complete. + + recovery_done: + description: >- + Socratic Code-Theory Recovery complete. Four documentation artifacts + produced (PRD, use-case spec, arc42, ADRs) plus review reports. + OPEN_QUESTIONS-.md is the living gap register. + default_instructions: > + Socratic Code-Theory Recovery is complete. + + **Deliverables produced:** + + - `docs/specs/prd-.md` — Product Requirements Document + - `docs/specs/use-cases-.md` — Cockburn Fully Dressed + use-case specification + system interface specs + - `docs/arc42/arc42-.md` — arc42 architecture documentation + (all 12 chapters) + - `docs/specs/adrs/-adr-NNN-*.md` — Nygard ADRs with + Pugh Matrices + - `docs/reports/fagan-inspection-.md` — inspection log + - `docs/reports/atam-.md` — ATAM results + - `docs/reports/review-summary-.md` — review summary + + **Living gap register:** + + `OPEN_QUESTIONS-.md` contains all items that could not + be recovered from code alone and were deferred by the team. Treat this + file as a living register — revisit it at each release. + + **Spec drift:** + + Re-run Phase 1 against the current codebase before each release. Diff + the new `QUESTION_TREE-.md` against the existing + documentation to surface: + - **NEW**: present in code, not yet in spec + - **CHANGED**: spec and code have diverged + - **DEAD**: in spec, but no longer in code + + **Next bounded context:** + + Pick the next bounded context only when this one's documentation is + being actively used. Breadth-first recovery across a whole system + produces shallow trees everywhere — depth on one context first. + + $DONE_DEFAULT + transitions: [] From 61deb562af802bc3855375088cc861310505da6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Tue, 16 Jun 2026 07:42:23 +0200 Subject: [PATCH 2/5] feat(workflows): add agent delegation to socratic-recovery workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Instructs the LLM to delegate the three context-heavy operations to sub-agents with explicit task descriptions: - question_tree STEP 2: delegates Phase 1 codebase reading to a single agent; agent returns only after both QUESTION_TREE and OPEN_QUESTIONS files are written and sanity-checked. - synthesize_documentation STEP 1: delegates the four synthesis artifacts to four parallel agents (PRD, use-case spec, arc42, ADRs); each agent receives the full traceability rules and returns only after its file is written and self-checked. - review_and_rework STEP 1: delegates the three review passes (Fagan Inspection, Traceability Check, ATAM) to three parallel agents; each agent receives all six input files and writes its report independently. Instructions use 'ask the agent specifically to...' phrasing — no agent role names, task description with exact inputs and expected output only. --- .beads/issues.jsonl | 7 +- .beads/last-touched | 2 +- ...socratic-architecture-recovery-workflow.md | 6 + resources/workflows/socratic-recovery.yaml | 110 ++++++++++-------- 4 files changed, 74 insertions(+), 51 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index d3a7e0a4..b8ada62d 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -387,7 +387,12 @@ {"id":"responsible-vibe-35.4.1","title":"Code cleanup: scan for debug/TODO artifacts in both new files","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.336567+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:21:56.914068+02:00","closed_at":"2026-06-16T07:21:56.914068+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.1","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.2","title":"Documentation review: check plan file completeness and update if needed","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.493699+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:22:28.679886+02:00","closed_at":"2026-06-16T07:22:28.679886+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.2","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.3","title":"Final validation: run full test suite","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.64241+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:23:33.765583+02:00","closed_at":"2026-06-16T07:23:33.765583+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.3","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} -{"id":"responsible-vibe-35.4.4","title":"Create PR","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.791302+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:21:46.791302+02:00","dependencies":[{"issue_id":"responsible-vibe-35.4.4","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.4","title":"Create PR","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.791302+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:24:49.34277+02:00","closed_at":"2026-06-16T07:24:49.34277+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.4","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.5","title":"Design: agent delegation + phase split strategy","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:32.678291+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:30:35.837569+02:00","closed_at":"2026-06-16T07:30:35.837569+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.5","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.6","title":"Update socratic-recovery.yaml: add agent delegation instructions","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:32.82452+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:40:39.778182+02:00","closed_at":"2026-06-16T07:40:39.778182+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.6","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.7","title":"Final validation: run tests after changes","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:32.968737+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:42:05.101384+02:00","closed_at":"2026-06-16T07:42:05.101384+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.7","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.8","title":"Amend commit and push","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:33.108786+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:30:33.108786+02:00","dependencies":[{"issue_id":"responsible-vibe-35.4.8","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.9","title":"Update socratic-recovery.yaml: agent delegation for question_tree, synthesize, review states","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:40:43.661831+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:42:04.990844+02:00","closed_at":"2026-06-16T07:42:04.990844+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.9","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-36","title":"workflows: minor (development-plan-feat-socratic-architecture-recovery-workflow.md)","description":"Create a new workflow YAML file () that guides an LLM through the **Socratic Code-Theory Recovery** method described in Ralf Müller's blog post. This workflow is the successor/complement to for retrospective/brownfield engineering. Instead of C4-based analysis, it uses arc42 as the documentation target, and uniquely produces an **OPEN_QUESTIONS list** (the more valuable artifact) alongside architecture docs.","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:52.947814+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:52.947814+02:00"} {"id":"responsible-vibe-36.1","title":"Explore","description":"Understand the problem, analyze existing patterns, and design your approach. Consider the scope and impact of the change. **STEP 1: Analyze Requirements** - If exists: Use it to understand the required changes - Otherwise: Document requirements in your task management system **STEP 2: Review Design Approach** - If exists: Respect the design approach documented in - Otherwise: Design your approach based on the problem analysis **STEP 3: Document Decisions** - Document your analysis and design decisions - Create tasks to guide implementation - Focus on analysis and design only - do not write any code yet","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:53.112518+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:53.112518+02:00","dependencies":[{"issue_id":"responsible-vibe-36.1","depends_on_id":"responsible-vibe-36","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-36.2","title":"Implement","description":"Write clean, focused code for the minor enhancement, test your changes, and prepare for commit. **STEP 1: Review Design and Requirements** - If exists: Follow your design from - Otherwise: Elaborate design options and present them to the user - If exists: Ensure the relevant requirements from are met - Otherwise: Ensure existing requirements are met based on your task context **STEP 2: Implement Changes** - Write clean, focused code for the minor enhancement - Test your changes to ensure they work correctly and don't break existing functionality **STEP 3: Prepare for Finalization** - Update task progress as needed - Prepare documentation and commit when ready","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:53.272944+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:53.272944+02:00","dependencies":[{"issue_id":"responsible-vibe-36.2","depends_on_id":"responsible-vibe-36","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-36.2","depends_on_id":"responsible-vibe-36.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} diff --git a/.beads/last-touched b/.beads/last-touched index 5cb1a906..334d1417 100644 --- a/.beads/last-touched +++ b/.beads/last-touched @@ -1 +1 @@ -responsible-vibe-35.4.4 +responsible-vibe-35.4.9 diff --git a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md index 47fdd1a0..1a5e5678 100644 --- a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md +++ b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md @@ -246,4 +246,10 @@ Create a new workflow YAML file (`socratic-recovery.yaml`) that guides an LLM th - All output paths use `.md` (not `.adoc` as in original blog post prompts — normalised throughout) - No debug artifacts, no TODOs, no commented-out code in either file - Integration tests pass (`test/integration/workflow-configuration.test.ts`) +- **Agent delegation added** (post-PR amendment): three states now instruct the LLM to delegate + heavy tasks to agents with explicit "ask the agent specifically to..." phrasing: + - `question_tree` STEP 2: Phase 1 codebase read → single agent, returns only after both files written + - `synthesize_documentation` STEP 1: 4 artifacts → 4 parallel agents (A: PRD, B: use-cases, C: arc42, D: ADRs) + - `review_and_rework` STEP 1: 3 review passes → 3 parallel agents (A: Fagan, B: Traceability, C: ATAM) + No agent role names used — instructions describe the task, inputs, and expected output only. diff --git a/resources/workflows/socratic-recovery.yaml b/resources/workflows/socratic-recovery.yaml index 6f809d4a..5b0e82c3 100644 --- a/resources/workflows/socratic-recovery.yaml +++ b/resources/workflows/socratic-recovery.yaml @@ -65,9 +65,16 @@ states: **STEP 2 — Run Phase 1: Build the Question Tree.** - Copy the following prompt verbatim into your working context. Replace - `[bounded context path]` with the actual path the user provided and - `[context-name]` with the kebab-case name from STEP 0. + Delegate this step to an agent. Ask the agent specifically to: perform + Socratic Code-Theory Recovery Phase 1 on the bounded context at + [bounded context path], follow the prompt below exactly, and write the + two output files (QUESTION_TREE-[context-name].md and + OPEN_QUESTIONS-[context-name].md) to the repository root before + returning. Do not return intermediate results — only return once both + files are written and the sanity-check (Step 3 of the prompt) is + complete. + + The prompt for the agent: ``` You are performing Socratic Code-Theory Recovery on a brownfield bounded @@ -314,8 +321,26 @@ states: **STEP 1 — Run Phase 2: Synthesize Documentation.** - Copy the following prompt verbatim. Replace `[context-name]` with the - kebab-case context name used in Phase 1. + Delegate the four artifacts to four agents running in parallel. For each + agent, ask it specifically to: read QUESTION_TREE-[context-name].md and + OPEN_QUESTIONS-[context-name].md, follow the traceability rules in the + prompt below, synthesize only its assigned artifact, write the file to + the correct path, and return only after the file is written and the + traceability self-check (no Q-IDs in output, every code claim has + file:line, every deferred item is labelled) is complete. + + - Agent A: synthesize docs/specs/prd-[context-name].md from the Q1 + branch of the Question Tree. + - Agent B: synthesize docs/specs/use-cases-[context-name].md from the + Q2 branch. + - Agent C: synthesize docs/arc42/arc42-[context-name].md (all 12 + chapters) from the Q3 branch, with Chapter 10 from Q4 scenarios. + - Agent D: synthesize docs/specs/adrs/[context-name]-adr-NNN-*.md + (one file per Q3.9 decision) from the Q3.9 branch. + + Give every agent the full prompt below so each understands the + traceability rules. Replace `[context-name]` with the kebab-case context + name used in Phase 1. ``` You are performing Phase 2 of Socratic Code-Theory Recovery. @@ -462,9 +487,14 @@ states: would be biased. Please start a new session for the review, ideally with a different model." Do not proceed with review in that case. - **STEP 1 — Read the artifacts.** + **STEP 1 — Run the three review passes in parallel.** + + Delegate each pass to a separate agent. Give every agent the six input + files listed below so it can read them independently. Ask each agent + specifically to read those files, perform its assigned pass, write its + report file, and return only after the report is written. - Read all six files: + Input files for all agents: - `docs/specs/prd-.md` - `docs/specs/use-cases-.md` - `docs/arc42/arc42-.md` @@ -472,47 +502,29 @@ states: - `QUESTION_TREE-.md` (for traceability) - `OPEN_QUESTIONS-.md` (for gap verification) - **STEP 2 — Fagan Inspection.** - - Evaluate each document against: - - **Completeness**: Every required section present? Chapters marked - "No information" are acceptable; blank or missing chapters are defects. - - **Clarity**: Ambiguous statements? Undefined terms? - - **Consistency**: Do documents contradict each other? - - **Verifiability**: Are claims stated in a way that can be tested or - confirmed? - - Log each defect with: - - Document + section - - Severity: Major (blocks use of the document) or Minor (reduces quality) - - Description - - Write defects to `docs/reports/fagan-inspection-.md`. - - **STEP 3 — Traceability Check.** - - 1. For every code-derived claim in the four documents, verify the cited - `file:line` exists and contains the claimed fact. - 2. Verify all team-supplied facts are marked `(team answer)`. - 3. List any claims that are: - - Uncited (no `file:line` and no `(team answer)` marker) - - Wrongly cited (the cited location does not support the claim) - - Append traceability defects to `docs/reports/fagan-inspection-.md` - or write a separate `docs/reports/traceability-.md`. - - **STEP 4 — ATAM (Architecture Tradeoff Analysis).** - - 1. Read Chapter 10 (Quality Requirements) of `arc42-.md`. - 2. Read each ADR's Pugh Matrix. - 3. Evaluate: do the ADR trade-offs actually address the quality goals - in Chapter 10? - 4. If Q4.9 (quality-goal priority) was `(deferred)`, mark the ATAM as - **provisional** — the ranking is assumed, not confirmed. - - Write results to `docs/reports/atam-.md`. - - **STEP 5 — Fix confirmed defects.** + - Agent A — Fagan Inspection: ask it specifically to evaluate + completeness (every required section present; "No information" is + acceptable, blank is a defect), clarity (ambiguous statements, + undefined terms), consistency (contradictions across documents), and + verifiability (claims testable or confirmable). Log each defect with + document+section, severity (Major / Minor), and description. Write + results to `docs/reports/fagan-inspection-.md`. + + - Agent B — Traceability Check: ask it specifically to scan every + code-derived claim in the four synthesis documents, verify each + cited `file:line` exists and contains the claimed fact, verify all + team-supplied facts are marked `(team answer)`, and list any uncited + or wrongly-cited claims as defects. Write results to + `docs/reports/traceability-.md`. + + - Agent C — ATAM: ask it specifically to read Chapter 10 (Quality + Requirements) of the arc42 document and each ADR's Pugh Matrix, + evaluate whether the ADR trade-offs address the quality goals in + Chapter 10, and — if Q4.9 (quality-goal priority) was `(deferred)` + — mark the entire ATAM as provisional. Write results to + `docs/reports/atam-.md`. + + **STEP 2 — Fix confirmed defects.** - Fix defects that have wrong content or missing citations in the source documents. @@ -520,7 +532,7 @@ states: NOT filling in a gap with speculation. - `(deferred)` gaps are NOT defects. Do not fill them. - **STEP 6 — Write review summary.** + **STEP 3 — Write review summary.** Write `docs/reports/review-summary-.md` with: - Total defects found (major / minor) From d569dc13da3dd32c9b349692114ca660bd7a44f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Tue, 16 Jun 2026 08:27:41 +0200 Subject: [PATCH 3/5] feat(workflows): refactor socratic-recovery workflow prose MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four improvements: 1. Strip internal method references — remove all 'Phase 1/2' and 'Socratic Code-Theory Recovery' wording from state instructions. The workflow implements the method; naming it internally adds noise. 2. Named fenced blocks for agent prompts — each prompt the LLM should delegate is now under a heading ('Agent prompt:', 'Agent prompt for Fagan Inspection:', etc.) and inside a fenced code block, so the delegating LLM can identify and pass the exact text. 3. Clarify setup_project_docs vs synthesis paths — STEP 2 of question_tree and STEP 2 of synthesize_documentation now explicitly distinguish: - .vibe/docs/architecture.md and .vibe/docs/requirements.md are structural reference templates (created by setup_project_docs) - docs/arc42/, docs/specs/ are the deliverable output paths 4. Tighten recovery_done — instructions now open with 'Present the following summary to the user' giving the LLM a concrete action, followed by the deliverable list, gap register note, spec-drift guidance, and $DONE_DEFAULT. --- .beads/issues.jsonl | 3 +- .beads/last-touched | 2 +- ...socratic-architecture-recovery-workflow.md | 5 + resources/workflows/socratic-recovery.yaml | 679 ++++++++---------- 4 files changed, 316 insertions(+), 373 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index b8ada62d..fa0d4899 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -385,13 +385,14 @@ {"id":"responsible-vibe-35.3.3","title":"Validate YAML against schema","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:10:56.273247+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:16:33.479893+02:00","closed_at":"2026-06-16T07:16:33.479893+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.3.3","depends_on_id":"responsible-vibe-35.3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4","title":"Commit","description":"Ensure code quality and documentation accuracy through systematic cleanup and review. **STEP 1: Code Cleanup** Systematically clean up development artifacts: 1. **Remove Debug Output**: Search for and remove all temporary debug output statements used during development. Look for language-specific debug output methods (console logging, print statements, debug output functions). Remove any debugging statements that were added for development purposes. 2. **Review TODO/FIXME Comments**: - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred - Remove completed TODOs - Convert remaining TODOs to proper issue tracking if needed 3. **Remove Debugging Code Blocks**: - Remove temporary debugging code, test code blocks, and commented-out code - Clean up any experimental code that's no longer needed - Ensure proper error handling replaces temporary debug logging **STEP 2: Documentation Review** Review and update documentation to reflect final implementation: 1. **Update Long-Term Memory Documents**: Based on what was actually implemented: - If exists: Update it if requirements changed during development - If exists: Update it if architectural impacts were identified - If exists: Update it if design details were refined or changed - Otherwise: Document any changes in the plan file 2. **Compare Against Implementation**: Review documentation against actual implemented functionality 3. **Update Changed Sections**: Only modify documentation sections that have functional changes 4. **Remove Development Progress**: Remove references to development iterations, progress notes, and temporary decisions 5. **Focus on Final State**: Ensure documentation describes the final implemented state, not the development process 6. **Ask User to Review Document Updates** **STEP 3: Final Validation** - Run existing tests to ensure cleanup didn't break functionality - Verify documentation accuracy with a final review - Ensure code is ready for production/delivery Update task progress and mark completed work as you finalize the feature. ","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:53:53.480495+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:53:53.480495+02:00","dependencies":[{"issue_id":"responsible-vibe-35.4","depends_on_id":"responsible-vibe-35","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-35.4","depends_on_id":"responsible-vibe-35.3","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.1","title":"Code cleanup: scan for debug/TODO artifacts in both new files","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.336567+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:21:56.914068+02:00","closed_at":"2026-06-16T07:21:56.914068+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.1","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.10","title":"Refactor socratic-recovery.yaml: strip phase wording, fix agent prompts, clarify setup_project_docs vs synthesis, tighten recovery_done","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T08:24:33.824849+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T08:27:22.247525+02:00","closed_at":"2026-06-16T08:27:22.247525+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.10","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.2","title":"Documentation review: check plan file completeness and update if needed","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.493699+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:22:28.679886+02:00","closed_at":"2026-06-16T07:22:28.679886+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.2","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.3","title":"Final validation: run full test suite","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.64241+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:23:33.765583+02:00","closed_at":"2026-06-16T07:23:33.765583+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.3","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.4","title":"Create PR","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.791302+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:24:49.34277+02:00","closed_at":"2026-06-16T07:24:49.34277+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.4","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.5","title":"Design: agent delegation + phase split strategy","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:32.678291+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:30:35.837569+02:00","closed_at":"2026-06-16T07:30:35.837569+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.5","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.6","title":"Update socratic-recovery.yaml: add agent delegation instructions","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:32.82452+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:40:39.778182+02:00","closed_at":"2026-06-16T07:40:39.778182+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.6","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.7","title":"Final validation: run tests after changes","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:32.968737+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:42:05.101384+02:00","closed_at":"2026-06-16T07:42:05.101384+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.7","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} -{"id":"responsible-vibe-35.4.8","title":"Amend commit and push","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:33.108786+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:30:33.108786+02:00","dependencies":[{"issue_id":"responsible-vibe-35.4.8","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.8","title":"Amend commit and push","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:30:33.108786+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:42:40.638992+02:00","closed_at":"2026-06-16T07:42:40.638992+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.8","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.9","title":"Update socratic-recovery.yaml: agent delegation for question_tree, synthesize, review states","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:40:43.661831+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:42:04.990844+02:00","closed_at":"2026-06-16T07:42:04.990844+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.9","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-36","title":"workflows: minor (development-plan-feat-socratic-architecture-recovery-workflow.md)","description":"Create a new workflow YAML file () that guides an LLM through the **Socratic Code-Theory Recovery** method described in Ralf Müller's blog post. This workflow is the successor/complement to for retrospective/brownfield engineering. Instead of C4-based analysis, it uses arc42 as the documentation target, and uniquely produces an **OPEN_QUESTIONS list** (the more valuable artifact) alongside architecture docs.","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:52.947814+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:52.947814+02:00"} {"id":"responsible-vibe-36.1","title":"Explore","description":"Understand the problem, analyze existing patterns, and design your approach. Consider the scope and impact of the change. **STEP 1: Analyze Requirements** - If exists: Use it to understand the required changes - Otherwise: Document requirements in your task management system **STEP 2: Review Design Approach** - If exists: Respect the design approach documented in - Otherwise: Design your approach based on the problem analysis **STEP 3: Document Decisions** - Document your analysis and design decisions - Create tasks to guide implementation - Focus on analysis and design only - do not write any code yet","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:15:53.112518+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:15:53.112518+02:00","dependencies":[{"issue_id":"responsible-vibe-36.1","depends_on_id":"responsible-vibe-36","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} diff --git a/.beads/last-touched b/.beads/last-touched index 334d1417..d32b061a 100644 --- a/.beads/last-touched +++ b/.beads/last-touched @@ -1 +1 @@ -responsible-vibe-35.4.9 +responsible-vibe-35.4.10 diff --git a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md index 1a5e5678..899e6d14 100644 --- a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md +++ b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md @@ -252,4 +252,9 @@ Create a new workflow YAML file (`socratic-recovery.yaml`) that guides an LLM th - `synthesize_documentation` STEP 1: 4 artifacts → 4 parallel agents (A: PRD, B: use-cases, C: arc42, D: ADRs) - `review_and_rework` STEP 1: 3 review passes → 3 parallel agents (A: Fagan, B: Traceability, C: ATAM) No agent role names used — instructions describe the task, inputs, and expected output only. +- **Workflow prose refactored** (second amendment): + 1. "Phase 1/2" and "Socratic Code-Theory Recovery" wording stripped from all state instructions — the workflow implements the method; no need to name it internally. + 2. Agent prompts wrapped in named fenced blocks (`**Agent prompt:**`, `**Agent prompt for Fagan Inspection:**`, etc.) so the receiving LLM knows exactly what text to delegate. + 3. `setup_project_docs` vs synthesis paths clarified: `.vibe/docs/architecture.md` and `.vibe/docs/requirements.md` are structural *reference templates*; the four deliverable files go to `docs/arc42/`, `docs/specs/` (explicitly distinguished in both `question_tree` STEP 2 and `synthesize_documentation` STEP 2). + 4. `recovery_done` tightened: instructions now explicitly say "Present the following summary to the user" — the LLM has a concrete action (present + `$DONE_DEFAULT`). diff --git a/resources/workflows/socratic-recovery.yaml b/resources/workflows/socratic-recovery.yaml index 5b0e82c3..ba616362 100644 --- a/resources/workflows/socratic-recovery.yaml +++ b/resources/workflows/socratic-recovery.yaml @@ -2,7 +2,7 @@ --- name: 'socratic-recovery' description: >- - Brownfield architecture recovery using Socratic Code-Theory Recovery (Naur, 1985). + Brownfield architecture recovery for undocumented codebases. Builds a hierarchical Question Tree from source code, surfaces OPEN_QUESTIONS for the team to answer, then synthesizes arc42 documentation, a PRD, Cockburn use-case spec, and Nygard ADRs — with an independent Fagan/ATAM review pass. @@ -31,192 +31,157 @@ metadata: states: question_tree: description: >- - Set up arc42 + Cockburn use-case documentation skeleton, then run Phase 1 - Socratic Code-Theory Recovery. Builds QUESTION_TREE-.md and - OPEN_QUESTIONS-.md for a named bounded context. + Set up arc42 + Cockburn use-case documentation skeleton, then build a + hierarchical Question Tree from the codebase. Produces + QUESTION_TREE-.md and OPEN_QUESTIONS-.md + for a named bounded context. allowed_file_patterns: - 'docs/**/*.md' - 'QUESTION_TREE-*.md' - 'OPEN_QUESTIONS-*.md' default_instructions: > - You are starting Phase 1 of Socratic Code-Theory Recovery on a brownfield - bounded context. + **STEP 1 — Confirm the bounded context.** - **STEP 0 — Ask for the bounded context if not already provided.** - - Before doing anything else, confirm: + Before doing anything else, confirm with the user: 1. The path to the bounded context (directory or set of directories). NEVER default to CWD — always ask. 2. A short kebab-case context name (e.g. `auth`, `order-service`, - `payment-gateway`). This name is used in every output file name so + `payment-gateway`). This name is appended to every output file so that sequential runs on different contexts never overwrite each other. - **STEP 1 — Set up documentation skeleton.** + **STEP 2 — Set up documentation skeleton.** Call: `setup_project_docs({ architecture: "arc42", requirements: "cockburn-use-cases", design: "none" })` - This creates: - - An arc42 Markdown skeleton (12 chapters) in the docs/ tree. - - A Cockburn Fully Dressed use-case template in the docs/ tree. + This creates two structural reference files in `.vibe/docs/`: + - `.vibe/docs/architecture.md` — arc42 skeleton (12 chapters). Use this + as the chapter structure reference when filling the arc42 output file + later. + - `.vibe/docs/requirements.md` — Cockburn Fully Dressed use-case + template. Use this as the section structure reference when filling the + use-case output file later. - Read both created files so you understand their structure before - generating content. + Read both files now so you understand their structure. - **STEP 2 — Run Phase 1: Build the Question Tree.** + **STEP 3 — Build the Question Tree.** - Delegate this step to an agent. Ask the agent specifically to: perform - Socratic Code-Theory Recovery Phase 1 on the bounded context at - [bounded context path], follow the prompt below exactly, and write the - two output files (QUESTION_TREE-[context-name].md and - OPEN_QUESTIONS-[context-name].md) to the repository root before - returning. Do not return intermediate results — only return once both - files are written and the sanity-check (Step 3 of the prompt) is - complete. + Delegate this step to an agent. Ask the agent specifically to: read the + codebase at [bounded context path], build a hierarchical Question Tree by + recursively decomposing five root questions down to leaf level, classify + every leaf as [ANSWERED] (with file:line evidence) or [OPEN] (with + category and role), run the sanity-check described in the prompt, and + write both output files before returning. - The prompt for the agent: + **Agent prompt:** ``` - 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 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. 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 - - One node carries a FIXED third level too: Q3.2 (Architecture - Constraints) always emits exactly these three sub-nodes, mirroring the - constraint kinds arc42 Chapter 2 distinguishes: - Q3.2.1 technical constraints — language, runtime, mandated - frameworks/libraries - Q3.2.2 organizational/process constraints — git workflow, branching, - release process, review rules - Q3.2.3 conventional constraints — naming, file layout, code-style - rules, commit conventions - For the Q3.2 branch specifically, look beyond source code: CLAUDE.md / - AGENTS.md, CONTRIBUTING files, CI workflow definitions, and - linter/formatter configs are valid evidence sources — cite them - file:line like any other evidence. Constraints of these kinds rarely - live in dense code, so a code-density-driven decomposition would walk - right past them. - - 3. Below the fixed second level, decompose ADAPTIVELY and code-driven. - A node is a leaf ONLY when its question can be answered with specific - `file:line` (or `file::function`) evidence, or definitively marked - [OPEN]. If the honest answer would still be coarse — a whole directory - as evidence, "the building blocks are these four packages", a single - paragraph standing in for an entire arc42 chapter — the node is NOT a - leaf yet. Decompose it further ("building blocks?" -> "building blocks - of the tool subsystem?" -> "...of the agent loop?") until every leaf - maps to one specific, citable piece of code. - - Tree depth therefore tracks code density: a small bounded context - yields a shallow tree, a large one a deep tree — you do not have to - guess the right bounded-context granularity up front. Backstop against - runaway recursion: do not decompose more than four levels below a fixed - node. If a leaf is still too coarse at that depth, mark it [OPEN] - (Category: business-context or design-rationale) and note that the - bounded context may be too large to recover in one pass. - - The fixed second level (Q1.1-Q5.5) is the SAME on every run, so the - skeleton stays diffable; only the depth below it is adaptive. 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: - - [ANSWERED] - - You found the answer in the code. - - Cite the evidence as : or ::. - - Be exact. No "see X for details." - - A directory or a bare folder path is NOT valid evidence. If the - only honest cite is a directory, the leaf still covers too much — - go back to step 3 and decompose it further. - - [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. - - Quality (the Q4 branch) is not wholly team knowledge. Where the code - shows measurable behaviour — a timeout, a truncation limit, a budget, - a retry policy, the threats and test concept from Q3.8 — write it as - an [ANSWERED] quality scenario with file:line. Never invent a target - number. Only the quality-goal ranking (Q4.9) is [OPEN]. - - 5. Output two files in Markdown, named after the bounded context so that - sequential runs on different contexts never overwrite each other: - - QUESTION_TREE-[context-name].md - - 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-[context-name].md - - Only the [OPEN] leaves, copied verbatim from the Question Tree file - - 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 - the answered tree into PRD, specification, arc42, and ADRs — only after the - team has filled in the [OPEN] leaves. + Build a hierarchical Question Tree for the codebase at + [bounded context path]. + + Start with these five root questions: + 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? + + The second level of the tree is FIXED — 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 + + Q3.2 (Architecture Constraints) carries a FIXED third level too: + Q3.2.1 technical constraints — language, runtime, mandated + frameworks/libraries + Q3.2.2 organizational/process constraints — git workflow, branching, + release process, review rules + Q3.2.3 conventional constraints — naming, file layout, code-style + rules, commit conventions + For Q3.2, also look beyond source code: CLAUDE.md / AGENTS.md, + CONTRIBUTING files, CI workflow definitions, and linter/formatter configs + are valid evidence sources — cite them file:line like any other evidence. + + Below the fixed second level, decompose ADAPTIVELY and code-driven. + A node is a leaf ONLY when its question can be answered with specific + file:line (or file::function) evidence, or definitively marked [OPEN]. + If the honest answer is still coarse (a whole directory, a bare package + name, a paragraph standing in for an entire arc42 chapter), the node is + NOT a leaf — decompose it further until every leaf maps to one specific, + citable piece of code. Do not decompose more than four levels below any + fixed node; if a leaf is still too coarse at that depth, mark it [OPEN] + (Category: business-context or design-rationale). + + For each leaf, classify it: + + [ANSWERED] + — You found the answer in the code. + — Cite evidence as : or ::. + — Be exact. A directory path is NOT valid evidence. + + [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. + + Quality (the Q4 branch) is not wholly team knowledge. Where the code + shows measurable behaviour — a timeout, a retry policy, a budget, a + truncation limit — write it as an [ANSWERED] quality scenario with + file:line. Only the quality-goal ranking (Q4.9) is [OPEN]. + + Write two output files in Markdown at the repository root. Name them + after the bounded context so sequential runs never overwrite each other: + + QUESTION_TREE-[context-name].md + — 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-[context-name].md + — Only the [OPEN] leaves, copied verbatim from the Question Tree. + — One section per Ask role (Product Owner, Architect, Developer, + Domain Expert, Operations) — emit every section even when empty + ("No open questions for this role"). + — Each question short enough to be answered in 1–3 sentences. + + Before returning, run this sanity-check: + 1. Pick three [ANSWERED] leaves at random. Verify each cited file:line + actually contains the claimed fact. If any citation is fabricated, + stop and report that the bounded context is too large. + 2. Scan for [ANSWERED] leaves whose evidence is a directory path or + whole file. Those need further decomposition. + 3. Count [OPEN] leaves: 10–15 is healthy for a small context; + 15–30 acceptable for a larger one; > 50 means the context is too + large — split it; < 5 means check decomposition depth. + + Do not write any documentation other than these two files. ``` - **STEP 3 — Sanity-check the output.** + **STEP 4 — Report to the user.** - After writing both files: - 1. Pick three `[ANSWERED]` leaves at random. Verify each cited `file:line` - actually contains the claimed fact. If any citation is fabricated, - the bounded context is too large — stop and tell the user to narrow - the scope and re-run. - 2. Scan for `[ANSWERED]` leaves whose evidence is a directory path or a - whole file, or whose answer summarises an entire arc42 chapter in one - paragraph. Those leaves need further decomposition — the tree stopped - too early. - 3. Count the `[OPEN]` leaves: - - 10–15: healthy for a small bounded context. - - 15–30: acceptable for a larger one. - - > 50: the bounded context is too large; split it and re-run Phase 1 - on each half before proceeding. - - < 5: check whether decomposition depth was sufficient. - - **STOP HERE.** Do NOT run Phase 2 in this state. Phase 2 begins only after - the team has answered or deferred every `[OPEN]` leaf. + After the agent returns, summarise the OPEN leaf count and health + assessment. Do NOT proceed to synthesis — that happens only after the + team has answered every [OPEN] leaf. transitions: - trigger: 'question_tree_complete' to: 'answer_open_questions' transition_reason: >- - Phase 1 complete. QUESTION_TREE and OPEN_QUESTIONS files written, - sanity-checked, and ready for team routing. + Question Tree and OPEN_QUESTIONS files written, sanity-checked, + and ready for team routing. additional_instructions: | Remind the user: @@ -227,8 +192,8 @@ states: - **Developer** — Q3 / implementation questions - **Domain Expert** — Q1–Q2 / domain knowledge questions - **Operations** — Q5 / operational / deployment questions - 3. Each person writes their answer **directly under the question**, - in plain prose (1–3 sentences is enough). + 3. Each person writes their answer **directly under the question** + in plain prose (1–3 sentences). 4. If a question cannot be answered now, mark it explicitly as `(deferred)` — do NOT leave it blank. 5. When every question has an answer or `(deferred)`, trigger @@ -243,49 +208,45 @@ states: allowed_file_patterns: - 'OPEN_QUESTIONS-*.md' default_instructions: > - You are the gate-keeper for Phase 1 → Phase 2 hand-off. - - **CRITICAL RULE: You must NEVER invent answers to [OPEN] leaves.** + **CRITICAL RULE: Never invent answers to [OPEN] leaves.** A deferred leaf is honest documentation. An invented answer is the - primary failure mode of this entire workflow — it produces documentation - that looks authoritative but is fabricated. If in doubt, mark as - (deferred). + primary failure mode of this workflow. If in doubt, mark as (deferred). - **STEP 1 — Read the current state of the file.** + **STEP 1 — Read the file.** Read `OPEN_QUESTIONS-.md`. (Ask the user for the - context-name if it was not carried over from the previous state.) + context-name if it is not clear from context.) **STEP 2 — Check the gate condition.** - Scan every `[OPEN]` leaf. For each one, check: + Scan every [OPEN] leaf. For each one, check: - Does it have a team answer written under it? (1–3 sentences of prose) - Does it have an explicit `(deferred)` marker? If ANY leaf has neither: - List all unanswered leaves grouped by Ask role. - - State clearly: "The following questions must be answered or explicitly - deferred before Phase 2 can run." + - State: "The following questions must be answered or explicitly + deferred before synthesis can run." - Do NOT proceed. Wait for the user to provide answers. If ALL leaves are answered or deferred: - Confirm: "Gate condition met — every [OPEN] leaf has a team answer or (deferred) marker." - - Suggest triggering `open_questions_answered` to proceed to Phase 2. + - Suggest triggering `open_questions_answered`. **STEP 3 — Assist with answering (optional).** - If the user asks for help formulating a question to send to a stakeholder, - help them write a clear, concise question. Do NOT provide the answer - yourself unless you can derive it from the codebase with a `file:line` - citation. + If the user asks for help formulating a question to send to a + stakeholder, help write a clear, concise question. Do NOT provide the + answer yourself unless you can derive it from the codebase with a + file:line citation. transitions: - trigger: 'open_questions_answered' to: 'synthesize_documentation' transition_reason: >- Every [OPEN] leaf has a team answer or (deferred) marker. - Phase 2 can now synthesize documentation from the answered tree. + Synthesis can now proceed. review_perspectives: - perspective: 'fabrication_check' prompt: >- @@ -300,164 +261,127 @@ states: synthesize_documentation: description: >- - Run Phase 2 — synthesize PRD, Cockburn use-case spec, arc42 (12 chapters), - and Nygard ADRs from the answered Question Tree. Code-derived claims cite - file:line; team answers are marked (team answer); deferred questions remain - explicit gaps — never filled by invention. + Synthesize PRD, Cockburn use-case spec, arc42 (12 chapters), and Nygard + ADRs from the answered Question Tree. Code-derived claims cite file:line; + team answers are marked (team answer); deferred questions remain explicit + gaps — never filled by invention. allowed_file_patterns: - 'docs/specs/prd-*.md' - 'docs/specs/use-cases-*.md' - 'docs/arc42/arc42-*.md' - 'docs/specs/adrs/*.md' default_instructions: > - You are running Phase 2 of Socratic Code-Theory Recovery. + **STEP 1 — Re-verify the gate condition.** - **STEP 0 — Re-verify the gate condition (belt-and-suspenders).** - - Read `OPEN_QUESTIONS-.md`. If ANY `[OPEN]` leaf has - neither a team answer nor an explicit `(deferred)` marker, STOP. - List the unanswered leaves and instruct the user to return to + Read `OPEN_QUESTIONS-.md`. If ANY [OPEN] leaf has neither + a team answer nor an explicit `(deferred)` marker, STOP. List the + unanswered leaves and instruct the user to return to `answer_open_questions`. - **STEP 1 — Run Phase 2: Synthesize Documentation.** - - Delegate the four artifacts to four agents running in parallel. For each - agent, ask it specifically to: read QUESTION_TREE-[context-name].md and - OPEN_QUESTIONS-[context-name].md, follow the traceability rules in the - prompt below, synthesize only its assigned artifact, write the file to - the correct path, and return only after the file is written and the - traceability self-check (no Q-IDs in output, every code claim has - file:line, every deferred item is labelled) is complete. - - - Agent A: synthesize docs/specs/prd-[context-name].md from the Q1 - branch of the Question Tree. - - Agent B: synthesize docs/specs/use-cases-[context-name].md from the - Q2 branch. - - Agent C: synthesize docs/arc42/arc42-[context-name].md (all 12 - chapters) from the Q3 branch, with Chapter 10 from Q4 scenarios. - - Agent D: synthesize docs/specs/adrs/[context-name]-adr-NNN-*.md - (one file per Q3.9 decision) from the Q3.9 branch. - - Give every agent the full prompt below so each understands the - traceability rules. Replace `[context-name]` with the kebab-case context - name used in Phase 1. + **STEP 2 — Synthesize the four output documents.** + + The two structural reference files created by `setup_project_docs` in + `.vibe/docs/` define the expected chapter and section structure: + - `.vibe/docs/architecture.md` — use as chapter structure guide when + writing `docs/arc42/arc42-.md` + - `.vibe/docs/requirements.md` — use as section structure guide when + writing `docs/specs/use-cases-.md` + + The four output files written in this state go to `docs/` (not to + `.vibe/docs/`). They are the deliverables; the `.vibe/docs/` files are + only reference templates. + + Delegate the four output files to four agents running in parallel. Give + every agent the traceability rules below. Ask each agent specifically to + read `QUESTION_TREE-.md` and + `OPEN_QUESTIONS-.md`, synthesize only its assigned output + file, run the traceability self-check, write the file, and return only + after the file is written. + + - Agent for `docs/specs/prd-.md`: ask it specifically + to synthesize the PRD from the Q1 branch of the Question Tree, + covering problem statement, target users, goals, success criteria, + scope boundaries, constraints, and open questions. + + - Agent for `docs/specs/use-cases-.md`: ask it + specifically to synthesize the use-case spec from the Q2 branch, + following the Cockburn Fully Dressed section structure in + `.vibe/docs/requirements.md`. Include Persona Use Cases (user-goal + level: actor, trigger, stakeholders & interests, preconditions, main + success scenario, extensions, postconditions, business rules), System + Use Cases per technical interface (input + validation, processing, + output + status codes, error responses), and Supplementary + Specifications (entity model, state machines, interface contracts, + validation rules). Add Gherkin acceptance criteria where applicable. + + - Agent for `docs/arc42/arc42-.md`: ask it specifically + to synthesize all 12 arc42 chapters from the Q3 branch, following + the chapter structure in `.vibe/docs/architecture.md`. Mark chapters + with no content as "No information" rather than fabricating content. + Chapter 10 (Quality Requirements) is an exception: synthesize it + from the answered Q4 quality scenarios plus the Q4.9 ranking — + reuse evidence already cited in Q3.8 (security scenarios cite STRIDE + T-IDs, maintainability scenarios the test concept). Only the + quality-goal ranking stays as a gap if Q4.9 was deferred. + + - Agent for `docs/specs/adrs/-adr-NNN-*.md`: ask it + specifically to synthesize one ADR file per significant design + decision from the Q3.9 branch. Use Nygard format (Title, Status, + Context, Decision, Consequences) and include a Pugh Matrix scoring + alternatives against Q4 quality goals on a -1 / 0 / +1 scale. + + **Traceability rules (give these to every agent):** ``` - You are performing Phase 2 of Socratic Code-Theory Recovery. - - Inputs: - - QUESTION_TREE-[context-name].md — the answered Question Tree from - Phase 1. - - OPEN_QUESTIONS-[context-name].md — same OPEN leaves, now with team - answers (or (deferred) markers) written under each question. - - Goal: synthesize documentation from the answered tree. Every claim must - trace back to a tree leaf — this is a build-time check, not a Q-ID stamped - into the text; Q-IDs do NOT appear in the final documents (see Rules for - traceability below). 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].md — Product Requirements Document - - Problem statement, target users, goals, success criteria, scope - boundaries, constraints, open questions - - Source: Q1 branch of QUESTION_TREE-[context-name].md - - Anchor: PRD (Cagan / Pichler) - - 2. docs/specs/use-cases-[context-name].md — 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-[context-name].md - - Anchor: Cockburn Use Cases - - 3. docs/arc42/arc42-[context-name].md — Architecture - - All 12 arc42 chapters. Mark chapters with no content as - "No information from Phase 1" rather than fabricating content. - - Chapter 10 (Quality Requirements) is an exception: synthesize it - from the [ANSWERED] Q4 quality scenarios plus the Q4.9 ranking. It - is never just an [OPEN] pointer. Reuse evidence already in Q3.8 — - Security scenarios cite the STRIDE T-IDs, Maintainability scenarios - the test concept. Only the goal ranking stays [OPEN]; "No - information" is legitimate here only if Q4 produced no answered - scenario at all. - - Source: Q3 branch of QUESTION_TREE-[context-name].md - - Anchor: arc42 (Starke / Hruschka) - - 4. docs/specs/adrs/[context-name]-adr-NNN-*.md — one ADR per - significant design decision. The context-name prefix keeps ADRs from - different bounded contexts from colliding in the shared adrs/ folder. - - 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-[context-name].md - - Anchor: ADR according to Nygard - - Rules for traceability: - - The synthesized documentation must be self-contained. The Question Tree - 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 - leaf — the reference to the code, the only durable, canonical artifact: - "The system uses Hexagonal Architecture [src/app/Ports.java, - src/adapter/JpaOrderRepository.java:30]." - Copy the Evidence line verbatim from the leaf; do not invent, shorten, - or re-derive file paths. A leaf with no Evidence line is not [ANSWERED] - and must not be cited as fact. - - Team-supplied facts have no code evidence — mark them (team answer): - "Sessions expire after 24 hours (team answer)." - - Deferred questions stay as explicit gaps: "Quality-goal priorities are - deferred and must be resolved before the next release." - - Do not introduce facts that do not appear in - QUESTION_TREE-[context-name].md or OPEN_QUESTIONS-[context-name].md. - If a section feels under-specified, leave it - under-specified — that is signal, not a defect. - ``` + Every claim in the output must trace to a leaf in the Question Tree. + Q-IDs must NOT appear in the output documents. + + - A claim from an [ANSWERED] leaf: cite the code evidence verbatim from + that leaf — e.g. "The system uses Hexagonal Architecture + [src/app/Ports.java, src/adapter/JpaOrderRepository.java:30]." Copy + the Evidence line exactly; do not invent, shorten, or re-derive paths. + A leaf with no Evidence line is not [ANSWERED] and must not be cited. - **STEP 2 — Verify the four artifacts.** + - A claim from a team answer: mark it (team answer) — e.g. "Sessions + expire after 24 hours (team answer)." - After writing all four artifacts, confirm: - 1. `docs/specs/prd-.md` — problem, users, success criteria, scope. - 2. `docs/specs/use-cases-.md` — Cockburn Fully Dressed persona - use cases + system use cases per interface. - 3. `docs/arc42/arc42-.md` — all 12 chapters (gaps marked, - not invented; Chapter 10 synthesized from Q4 scenarios). - 4. `docs/specs/adrs/-adr-NNN-*.md` — one Nygard ADR with - Pugh Matrix per Q3.9 decision. + - A deferred item: keep it as an explicit gap — e.g. "Quality-goal + priorities are deferred and must be resolved before the next release." - Check that no Q-IDs appear in the output documents. Check that every - code-derived claim has a file:line citation. Check that deferred items - are labelled "(deferred)", not left blank or filled with speculation. + Do not introduce facts that do not appear in the Question Tree or + OPEN_QUESTIONS file. If a section feels under-specified, leave it + under-specified — that is signal, not a defect. + + Before returning, self-check: no Q-IDs in output, every code-derived + claim has a file:line citation, every deferred item is labelled. + ``` + + **STEP 3 — Verify the four artifacts.** + + After all agents return, confirm: + 1. `docs/specs/prd-.md` — problem, users, success + criteria, scope. + 2. `docs/specs/use-cases-.md` — Cockburn Fully Dressed + persona use cases + system use cases per interface. + 3. `docs/arc42/arc42-.md` — all 12 chapters (gaps + marked, not invented; Chapter 10 synthesized from Q4 scenarios). + 4. `docs/specs/adrs/-adr-NNN-*.md` — one Nygard ADR + with Pugh Matrix per Q3.9 decision. transitions: - trigger: 'synthesis_complete' to: 'review_and_rework' transition_reason: >- - All four Phase 2 artifacts produced and verified. Ready for - independent Fagan Inspection, Traceability Check, and ATAM. + All four output documents produced and verified. Ready for + independent review. additional_instructions: | - **IMPORTANT — Independent Review Session Required** - - The review in the next state MUST run in a FRESH LLM session with no - memory of this synthesis session. Confirmation bias is a real risk: - a model that wrote the documentation will miss its own errors. + **IMPORTANT — Independent Review Session** - Ideally use a different model for the review session. At minimum, - start a brand-new conversation without any context from Phase 2. + The review in the next state should run in a fresh LLM session with + no memory of the synthesis session. A model that wrote the + documentation will miss its own errors. - Hand the reviewer these files: + Hand the reviewer: - `docs/specs/prd-.md` - `docs/specs/use-cases-.md` - `docs/arc42/arc42-.md` @@ -468,9 +392,9 @@ states: review_and_rework: description: >- Independent review of the four synthesized documents — Fagan Inspection, - Traceability Check, and ATAM. Must run in a FRESH session (different model - ideally). Fix confirmed defects only; leave (deferred) gaps as gaps. - Review results written to docs/reports/. + Traceability Check, and ATAM. Should run in a fresh session (different + model ideally). Fix confirmed defects only; leave (deferred) gaps as + gaps. Review results written to docs/reports/. allowed_file_patterns: - 'docs/reports/*.md' - 'docs/specs/prd-*.md' @@ -478,59 +402,73 @@ states: - 'docs/arc42/arc42-*.md' - 'docs/specs/adrs/*.md' default_instructions: > - You are performing an independent review of Socratic Recovery documentation. - - **IMPORTANT: This state should run in a new, independent LLM session.** + **IMPORTANT: This state should run in a fresh LLM session.** If you have memory of writing the documents you are about to review, - STOP and tell the user: "I wrote these documents. Review in this session - would be biased. Please start a new session for the review, ideally with - a different model." Do not proceed with review in that case. + stop and tell the user: "I wrote these documents — review in this + session would be biased. Please start a new session for the review." **STEP 1 — Run the three review passes in parallel.** - Delegate each pass to a separate agent. Give every agent the six input - files listed below so it can read them independently. Ask each agent - specifically to read those files, perform its assigned pass, write its - report file, and return only after the report is written. + Delegate each pass to a separate agent. Ask each agent specifically to + read the six input files listed in its prompt, perform its assigned + review, write its report file, and return only after the report is + written. - Input files for all agents: + Input files for all agents (substitute ): - `docs/specs/prd-.md` - `docs/specs/use-cases-.md` - `docs/arc42/arc42-.md` - `docs/specs/adrs/-adr-NNN-*.md` (all ADRs) - - `QUESTION_TREE-.md` (for traceability) - - `OPEN_QUESTIONS-.md` (for gap verification) - - - Agent A — Fagan Inspection: ask it specifically to evaluate - completeness (every required section present; "No information" is - acceptable, blank is a defect), clarity (ambiguous statements, - undefined terms), consistency (contradictions across documents), and - verifiability (claims testable or confirmable). Log each defect with - document+section, severity (Major / Minor), and description. Write - results to `docs/reports/fagan-inspection-.md`. - - - Agent B — Traceability Check: ask it specifically to scan every - code-derived claim in the four synthesis documents, verify each - cited `file:line` exists and contains the claimed fact, verify all - team-supplied facts are marked `(team answer)`, and list any uncited - or wrongly-cited claims as defects. Write results to - `docs/reports/traceability-.md`. - - - Agent C — ATAM: ask it specifically to read Chapter 10 (Quality - Requirements) of the arc42 document and each ADR's Pugh Matrix, - evaluate whether the ADR trade-offs address the quality goals in - Chapter 10, and — if Q4.9 (quality-goal priority) was `(deferred)` - — mark the entire ATAM as provisional. Write results to - `docs/reports/atam-.md`. + - `QUESTION_TREE-.md` + - `OPEN_QUESTIONS-.md` + + **Agent prompt for Fagan Inspection:** + + ``` + Read the six input files listed above. Evaluate each of the four + synthesis documents against: + - Completeness: every required section present? ("No information" is + acceptable; blank or missing sections are defects.) + - Clarity: ambiguous statements, undefined terms? + - Consistency: contradictions across documents? + - Verifiability: claims stated in a testable or confirmable way? + Log each defect with document + section, severity (Major / Minor), and + description. Write all defects to + `docs/reports/fagan-inspection-.md`. Return only after + the file is written. + ``` + + **Agent prompt for Traceability Check:** + + ``` + Read the six input files listed above. For every code-derived claim in + the four synthesis documents, verify that the cited file:line exists and + contains the claimed fact. Verify that all team-supplied facts are marked + (team answer). List any uncited or wrongly-cited claims as defects. Write + all findings to `docs/reports/traceability-.md`. Return + only after the file is written. + ``` + + **Agent prompt for ATAM:** + + ``` + Read the six input files listed above. Read Chapter 10 (Quality + Requirements) of the arc42 document and each ADR's Pugh Matrix. + Evaluate whether the ADR trade-offs actually address the quality goals in + Chapter 10. If the quality-goal ranking (Q4.9) was marked (deferred), + mark the entire ATAM result as provisional — the ranking is assumed, not + confirmed. Write results to `docs/reports/atam-.md`. + Return only after the file is written. + ``` **STEP 2 — Fix confirmed defects.** - Fix defects that have wrong content or missing citations in the source documents. - - Fixing means CORRECTING a wrong fact or adding a missing citation — - NOT filling in a gap with speculation. - - `(deferred)` gaps are NOT defects. Do not fill them. + - Fixing means correcting a wrong fact or adding a missing citation — + not filling in a gap with speculation. + - `(deferred)` gaps are not defects. Do not fill them. **STEP 3 — Write review summary.** @@ -552,23 +490,23 @@ states: to: 'recovery_done' transition_reason: >- Review clean — all defects resolved or confirmed as intentional gaps. - Socratic Recovery is complete. + Recovery is complete. recovery_done: description: >- - Socratic Code-Theory Recovery complete. Four documentation artifacts - produced (PRD, use-case spec, arc42, ADRs) plus review reports. - OPEN_QUESTIONS-.md is the living gap register. + Recovery complete. Four documentation artifacts produced (PRD, use-case + spec, arc42, ADRs) plus review reports. OPEN_QUESTIONS is the living + gap register. default_instructions: > - Socratic Code-Theory Recovery is complete. + Present the following summary to the user. - **Deliverables produced:** + **Deliverables:** - `docs/specs/prd-.md` — Product Requirements Document - `docs/specs/use-cases-.md` — Cockburn Fully Dressed use-case specification + system interface specs - - `docs/arc42/arc42-.md` — arc42 architecture documentation - (all 12 chapters) + - `docs/arc42/arc42-.md` — arc42 architecture + documentation (all 12 chapters) - `docs/specs/adrs/-adr-NNN-*.md` — Nygard ADRs with Pugh Matrices - `docs/reports/fagan-inspection-.md` — inspection log @@ -577,23 +515,22 @@ states: **Living gap register:** - `OPEN_QUESTIONS-.md` contains all items that could not - be recovered from code alone and were deferred by the team. Treat this - file as a living register — revisit it at each release. + `OPEN_QUESTIONS-.md` lists everything that could not be + recovered from code alone and was deferred by the team. Revisit it at + each release. - **Spec drift:** + **Spec drift — do this before every release:** - Re-run Phase 1 against the current codebase before each release. Diff - the new `QUESTION_TREE-.md` against the existing - documentation to surface: + Re-run the `question_tree` state against the current codebase and diff + the new `QUESTION_TREE-.md` against the existing docs: - **NEW**: present in code, not yet in spec - **CHANGED**: spec and code have diverged - **DEAD**: in spec, but no longer in code **Next bounded context:** - Pick the next bounded context only when this one's documentation is - being actively used. Breadth-first recovery across a whole system + Only start the next bounded context when this one's documentation is + actively being used. Breadth-first recovery across a whole system produces shallow trees everywhere — depth on one context first. $DONE_DEFAULT From ed17b8cf190bebaffb8ff47437abd062f0d45692 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Tue, 16 Jun 2026 12:01:21 +0200 Subject: [PATCH 4/5] feat(workflows): remove setup_project_docs from socratic-recovery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit setup_project_docs creates .vibe/docs/ files that the workflow engine uses only when states reference $ARCHITECTURE_DOC / $REQUIREMENTS_DOC macros. No state in this workflow uses those macros — all states work directly from QUESTION_TREE-.md and the docs/ output files. Arc42 and Cockburn Fully Dressed structures are baked into agent training; no runtime template file is needed. - Remove setup_project_docs call and 'read both files' instruction from question_tree STEP 2 (now STEP 2 is Build the Question Tree) - Renumber: old STEP 3 → STEP 2, old STEP 4 → STEP 3 - Remove .vibe/docs/ references from synthesize_documentation STEP 2; agents reference arc42 and Cockburn structures by name directly - Remove docs/**/*.md from question_tree allowed_file_patterns --- .beads/issues.jsonl | 1 + .beads/last-touched | 2 +- ...socratic-architecture-recovery-workflow.md | 1 + resources/workflows/socratic-recovery.yaml | 64 ++++++------------- 4 files changed, 21 insertions(+), 47 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index fa0d4899..579f17bd 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -386,6 +386,7 @@ {"id":"responsible-vibe-35.4","title":"Commit","description":"Ensure code quality and documentation accuracy through systematic cleanup and review. **STEP 1: Code Cleanup** Systematically clean up development artifacts: 1. **Remove Debug Output**: Search for and remove all temporary debug output statements used during development. Look for language-specific debug output methods (console logging, print statements, debug output functions). Remove any debugging statements that were added for development purposes. 2. **Review TODO/FIXME Comments**: - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred - Remove completed TODOs - Convert remaining TODOs to proper issue tracking if needed 3. **Remove Debugging Code Blocks**: - Remove temporary debugging code, test code blocks, and commented-out code - Clean up any experimental code that's no longer needed - Ensure proper error handling replaces temporary debug logging **STEP 2: Documentation Review** Review and update documentation to reflect final implementation: 1. **Update Long-Term Memory Documents**: Based on what was actually implemented: - If exists: Update it if requirements changed during development - If exists: Update it if architectural impacts were identified - If exists: Update it if design details were refined or changed - Otherwise: Document any changes in the plan file 2. **Compare Against Implementation**: Review documentation against actual implemented functionality 3. **Update Changed Sections**: Only modify documentation sections that have functional changes 4. **Remove Development Progress**: Remove references to development iterations, progress notes, and temporary decisions 5. **Focus on Final State**: Ensure documentation describes the final implemented state, not the development process 6. **Ask User to Review Document Updates** **STEP 3: Final Validation** - Run existing tests to ensure cleanup didn't break functionality - Verify documentation accuracy with a final review - Ensure code is ready for production/delivery Update task progress and mark completed work as you finalize the feature. ","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-15T12:53:53.480495+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-15T12:53:53.480495+02:00","dependencies":[{"issue_id":"responsible-vibe-35.4","depends_on_id":"responsible-vibe-35","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"responsible-vibe-35.4","depends_on_id":"responsible-vibe-35.3","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.1","title":"Code cleanup: scan for debug/TODO artifacts in both new files","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.336567+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:21:56.914068+02:00","closed_at":"2026-06-16T07:21:56.914068+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.1","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.10","title":"Refactor socratic-recovery.yaml: strip phase wording, fix agent prompts, clarify setup_project_docs vs synthesis, tighten recovery_done","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T08:24:33.824849+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T08:27:22.247525+02:00","closed_at":"2026-06-16T08:27:22.247525+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.10","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.11","title":"Remove setup_project_docs from question_tree and .vibe/docs references from synthesize_documentation","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T11:59:08.488509+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T12:01:20.958117+02:00","closed_at":"2026-06-16T12:01:20.958117+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.11","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.2","title":"Documentation review: check plan file completeness and update if needed","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.493699+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:22:28.679886+02:00","closed_at":"2026-06-16T07:22:28.679886+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.2","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.3","title":"Final validation: run full test suite","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.64241+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:23:33.765583+02:00","closed_at":"2026-06-16T07:23:33.765583+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.3","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.4","title":"Create PR","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.791302+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:24:49.34277+02:00","closed_at":"2026-06-16T07:24:49.34277+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.4","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} diff --git a/.beads/last-touched b/.beads/last-touched index d32b061a..690bcf9d 100644 --- a/.beads/last-touched +++ b/.beads/last-touched @@ -1 +1 @@ -responsible-vibe-35.4.10 +responsible-vibe-35.4.11 diff --git a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md index 899e6d14..73765611 100644 --- a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md +++ b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md @@ -257,4 +257,5 @@ Create a new workflow YAML file (`socratic-recovery.yaml`) that guides an LLM th 2. Agent prompts wrapped in named fenced blocks (`**Agent prompt:**`, `**Agent prompt for Fagan Inspection:**`, etc.) so the receiving LLM knows exactly what text to delegate. 3. `setup_project_docs` vs synthesis paths clarified: `.vibe/docs/architecture.md` and `.vibe/docs/requirements.md` are structural *reference templates*; the four deliverable files go to `docs/arc42/`, `docs/specs/` (explicitly distinguished in both `question_tree` STEP 2 and `synthesize_documentation` STEP 2). 4. `recovery_done` tightened: instructions now explicitly say "Present the following summary to the user" — the LLM has a concrete action (present + `$DONE_DEFAULT`). +- **`setup_project_docs` removed** (confirmed unnecessary): `.vibe/docs/` files serve the workflow engine only if a state references `$ARCHITECTURE_DOC`/`$REQUIREMENTS_DOC` macros. No state in this workflow uses those macros — all states work directly from `QUESTION_TREE-.md` and the `docs/` output files. The arc42 and Cockburn Fully Dressed structures are baked into agent training; no runtime template file is needed. `allowed_file_patterns` for `docs/**/*.md` also removed from `question_tree` (no docs/ files written there). diff --git a/resources/workflows/socratic-recovery.yaml b/resources/workflows/socratic-recovery.yaml index ba616362..59f56b5f 100644 --- a/resources/workflows/socratic-recovery.yaml +++ b/resources/workflows/socratic-recovery.yaml @@ -36,7 +36,6 @@ states: QUESTION_TREE-.md and OPEN_QUESTIONS-.md for a named bounded context. allowed_file_patterns: - - 'docs/**/*.md' - 'QUESTION_TREE-*.md' - 'OPEN_QUESTIONS-*.md' default_instructions: > @@ -49,22 +48,7 @@ states: `payment-gateway`). This name is appended to every output file so that sequential runs on different contexts never overwrite each other. - **STEP 2 — Set up documentation skeleton.** - - Call: - `setup_project_docs({ architecture: "arc42", requirements: "cockburn-use-cases", design: "none" })` - - This creates two structural reference files in `.vibe/docs/`: - - `.vibe/docs/architecture.md` — arc42 skeleton (12 chapters). Use this - as the chapter structure reference when filling the arc42 output file - later. - - `.vibe/docs/requirements.md` — Cockburn Fully Dressed use-case - template. Use this as the section structure reference when filling the - use-case output file later. - - Read both files now so you understand their structure. - - **STEP 3 — Build the Question Tree.** + **STEP 2 — Build the Question Tree.** Delegate this step to an agent. Ask the agent specifically to: read the codebase at [bounded context path], build a hierarchical Question Tree by @@ -170,7 +154,7 @@ states: Do not write any documentation other than these two files. ``` - **STEP 4 — Report to the user.** + **STEP 3 — Report to the user.** After the agent returns, summarise the OPEN leaf count and health assessment. Do NOT proceed to synthesis — that happens only after the @@ -280,17 +264,6 @@ states: **STEP 2 — Synthesize the four output documents.** - The two structural reference files created by `setup_project_docs` in - `.vibe/docs/` define the expected chapter and section structure: - - `.vibe/docs/architecture.md` — use as chapter structure guide when - writing `docs/arc42/arc42-.md` - - `.vibe/docs/requirements.md` — use as section structure guide when - writing `docs/specs/use-cases-.md` - - The four output files written in this state go to `docs/` (not to - `.vibe/docs/`). They are the deliverables; the `.vibe/docs/` files are - only reference templates. - Delegate the four output files to four agents running in parallel. Give every agent the traceability rules below. Ask each agent specifically to read `QUESTION_TREE-.md` and @@ -304,25 +277,24 @@ states: scope boundaries, constraints, and open questions. - Agent for `docs/specs/use-cases-.md`: ask it - specifically to synthesize the use-case spec from the Q2 branch, - following the Cockburn Fully Dressed section structure in - `.vibe/docs/requirements.md`. Include Persona Use Cases (user-goal - level: actor, trigger, stakeholders & interests, preconditions, main - success scenario, extensions, postconditions, business rules), System - Use Cases per technical interface (input + validation, processing, - output + status codes, error responses), and Supplementary - Specifications (entity model, state machines, interface contracts, - validation rules). Add Gherkin acceptance criteria where applicable. + specifically to synthesize the use-case spec from the Q2 branch + using Cockburn Fully Dressed format. Include Persona Use Cases + (user-goal level: actor, trigger, stakeholders & interests, + preconditions, main success scenario, extensions, postconditions, + business rules), System Use Cases per technical interface (input + + validation, processing, output + status codes, error responses), and + Supplementary Specifications (entity model, state machines, interface + contracts, validation rules). Add Gherkin acceptance criteria where + applicable. - Agent for `docs/arc42/arc42-.md`: ask it specifically - to synthesize all 12 arc42 chapters from the Q3 branch, following - the chapter structure in `.vibe/docs/architecture.md`. Mark chapters - with no content as "No information" rather than fabricating content. - Chapter 10 (Quality Requirements) is an exception: synthesize it - from the answered Q4 quality scenarios plus the Q4.9 ranking — - reuse evidence already cited in Q3.8 (security scenarios cite STRIDE - T-IDs, maintainability scenarios the test concept). Only the - quality-goal ranking stays as a gap if Q4.9 was deferred. + to synthesize all 12 arc42 chapters from the Q3 branch. Mark + chapters with no content as "No information" rather than fabricating + content. Chapter 10 (Quality Requirements) is an exception: + synthesize it from the answered Q4 quality scenarios plus the Q4.9 + ranking — reuse evidence already cited in Q3.8 (security scenarios + cite STRIDE T-IDs, maintainability scenarios the test concept). Only + the quality-goal ranking stays as a gap if Q4.9 was deferred. - Agent for `docs/specs/adrs/-adr-NNN-*.md`: ask it specifically to synthesize one ADR file per significant design From 4a472806f89d026ecbe46bbf366b0c758c89f6d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Tue, 16 Jun 2026 14:09:45 +0200 Subject: [PATCH 5/5] chore(workflows): remove cockburn-use-cases.md template No state in socratic-recovery.yaml uses setup_project_docs or the $REQUIREMENTS_DOC macro, so the template file is never read at runtime. The Cockburn Fully Dressed format is referenced by name in the synthesis agent instructions and needs no file backing. --- .beads/issues.jsonl | 1 + .beads/last-touched | 2 +- ...socratic-architecture-recovery-workflow.md | 4 +- .../requirements/cockburn-use-cases.md | 151 ------------------ 4 files changed, 4 insertions(+), 154 deletions(-) delete mode 100644 resources/templates/requirements/cockburn-use-cases.md diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 579f17bd..4be06005 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -387,6 +387,7 @@ {"id":"responsible-vibe-35.4.1","title":"Code cleanup: scan for debug/TODO artifacts in both new files","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.336567+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:21:56.914068+02:00","closed_at":"2026-06-16T07:21:56.914068+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.1","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.10","title":"Refactor socratic-recovery.yaml: strip phase wording, fix agent prompts, clarify setup_project_docs vs synthesis, tighten recovery_done","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T08:24:33.824849+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T08:27:22.247525+02:00","closed_at":"2026-06-16T08:27:22.247525+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.10","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.11","title":"Remove setup_project_docs from question_tree and .vibe/docs references from synthesize_documentation","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T11:59:08.488509+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T12:01:20.958117+02:00","closed_at":"2026-06-16T12:01:20.958117+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.11","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"responsible-vibe-35.4.12","title":"Remove cockburn-use-cases.md template","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T14:09:13.990646+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T14:09:45.331491+02:00","closed_at":"2026-06-16T14:09:45.331491+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.12","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.2","title":"Documentation review: check plan file completeness and update if needed","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.493699+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:22:28.679886+02:00","closed_at":"2026-06-16T07:22:28.679886+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.2","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.3","title":"Final validation: run full test suite","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.64241+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:23:33.765583+02:00","closed_at":"2026-06-16T07:23:33.765583+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.3","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} {"id":"responsible-vibe-35.4.4","title":"Create PR","status":"closed","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-06-16T07:21:46.791302+02:00","created_by":"Oliver Jägle","updated_at":"2026-06-16T07:24:49.34277+02:00","closed_at":"2026-06-16T07:24:49.34277+02:00","close_reason":"Closed","dependencies":[{"issue_id":"responsible-vibe-35.4.4","depends_on_id":"responsible-vibe-35.4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} diff --git a/.beads/last-touched b/.beads/last-touched index 690bcf9d..62681e83 100644 --- a/.beads/last-touched +++ b/.beads/last-touched @@ -1 +1 @@ -responsible-vibe-35.4.11 +responsible-vibe-35.4.12 diff --git a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md index 73765611..3b959cfd 100644 --- a/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md +++ b/.vibe/development-plan-feat-socratic-architecture-recovery-workflow.md @@ -241,8 +241,8 @@ Create a new workflow YAML file (`socratic-recovery.yaml`) that guides an LLM th ### Key Implementation Facts (final state) -- `resources/workflows/socratic-recovery.yaml`: 5 states, 589 lines, schema-valid -- `resources/templates/requirements/cockburn-use-cases.md`: 149 lines, lean structure-only template +- `resources/workflows/socratic-recovery.yaml`: 5 states, schema-valid, agent delegation on 3 states +- `resources/templates/requirements/cockburn-use-cases.md`: **deleted** — not needed; no state uses `$REQUIREMENTS_DOC`; Cockburn format referenced by name in agent instructions only - All output paths use `.md` (not `.adoc` as in original blog post prompts — normalised throughout) - No debug artifacts, no TODOs, no commented-out code in either file - Integration tests pass (`test/integration/workflow-configuration.test.ts`) diff --git a/resources/templates/requirements/cockburn-use-cases.md b/resources/templates/requirements/cockburn-use-cases.md deleted file mode 100644 index d07fb7ad..00000000 --- a/resources/templates/requirements/cockburn-use-cases.md +++ /dev/null @@ -1,151 +0,0 @@ - - -# Use-Case Specification: [System / Bounded Context Name] - ---- - -## 1. Persona Use Cases - - - -### UC-P01 [!] [Imperative Verb Phrase] (Primary Actor: [Role]) - -| Field | Value | -| ---------------------------- | -------------------------------------------------------------------------------------- | -| **Scope** | [System under discussion] | -| **Primary Actor** | [Who initiates and has the goal] | -| **Stakeholders & Interests** | [Every affected party and what they want — list all, even if absent from the scenario] | - -**Preconditions** — what must be true before the use case starts - -- [State of system + actor] - -**Trigger** — the observable event that initiates this use case - -- [Actor intention, not a UI control] - -**Minimal Guarantee** — holds even on every failure path - -- [System invariant that is never violated, even on cancellation or error] - -**Success Guarantee** — additionally true on full success - -- [Observable outcome when the use case completes successfully] - ---- - -**Main Success Scenario** - -1. [Actor action] -2. [System response] -3. [Actor action] -4. [System produces main outcome] - ---- - -**Extensions** — branch from the step number they occur at (e.g. 3a, 3b) - -**3a.** [Condition at step 3]: - -1. [System or actor response] - -- Resume at step N | Use case ends (failure) | Use case ends (success) - ---- - -**Business Rules** - -- [BR-01: Rule reference or inline statement] - ---- - -**Gherkin Acceptance Criteria** _(optional)_ - -```gherkin -Scenario: [Happy path] - Given [precondition] - When [trigger] - Then [success outcome] - -Scenario: [Extension 3a] - Given [precondition] - When [condition] - Then [expected behaviour] -``` - ---- - -### UC-P02 [!] [Title] (Primary Actor: [Role]) - - - ---- - -## 2. System Use Cases - - - -### UC-S01 [Interface Identifier — e.g. POST /orders] - -| Field | Value | -| ---------------------- | ------------------------------------- | -| **Caller / Publisher** | [Who invokes this interface] | -| **Protocol / Format** | [REST/JSON, gRPC, CloudEvent, CSV, …] | - -**Input & Validation** - -| Parameter | Type | Required | Constraint | -| --------- | -------- | -------- | ----------------- | -| `[param]` | `[type]` | Yes/No | [verifiable rule] | - -**Processing** - -1. [What the system does with valid input] - -**Output / Response** - -| Condition | Status | Payload | -| --------- | ----------------- | -------------------- | -| Success | `200 OK` | [schema or example] | -| [Error] | `400 Bad Request` | `{ "error": "..." }` | - ---- - -### UC-S02 [Interface Identifier] - - - ---- - -## 3. Supplementary Specifications - -### 3.1 Entity Model - -| Entity | Key Attributes | Relationships | -| ---------- | -------------- | ------------------ | -| `[Entity]` | `id`, `[attr]` | has-many `[Other]` | - -### 3.2 State Machines - -**[Entity] lifecycle:** - -| From | Event | To | Guard | -| --------- | --------- | --------- | ---------- | -| `[State]` | `[event]` | `[State]` | [optional] | - -### 3.3 Cross-Cutting Contracts - -- **[Contract]**: [Applies to which use cases and what it mandates] - -### 3.4 Business Rules - -| ID | Description | Authority | -| ------- | ----------- | ------------------------------ | -| `BR-01` | [Rule] | [Law / policy / domain expert] |