Fix issues with plan-docs QR being too overzealous

Author: solatis

skills/scripts/skills/planner/cli/plan.py

@@ -75,7 +75,7 @@
     "architect": {"init", "set-milestone", "set-intent", "set-decision",
                   "set-diagram", "add-diagram-node", "add-diagram-edge"},
     "developer": {"set-change"},
-    "tw": {"set-doc", "set-readme", "translate", "set-diagram-render"},
+    "tw": {"set-doc", "set-readme", "set-diagram-render"},
     "qr": {"validate"},
 }
 
@@ -854,25 +854,6 @@ def run(cls, args: argparse.Namespace) -> None:
 # =============================================================================
 
 
-class TranslateCommand(Command):
-    name = "translate"
-    help = "Translate plan.json to Markdown"
-    role = "tw"
-
-    @classmethod
-    def add_arguments(cls, p: argparse.ArgumentParser) -> None:
-        p.add_argument("--output", required=True, help="Output file path")
-
-    @classmethod
-    def run(cls, args: argparse.Namespace) -> None:
-        state_dir = get_state_dir()
-        plan = load_plan(state_dir)
-
-        md = translate_to_markdown(plan)
-
-        Path(args.output).write_text(md)
-        success(f"Translated to {args.output}")
-
 
 def translate_to_markdown(plan: "Plan") -> str:
     """Generate Markdown from plan.json."""
@@ -1242,7 +1223,6 @@ def run(cls, args: argparse.Namespace) -> None:
     SetDocCommand,
     SetReadmeCommand,
     SetDiagramRenderCommand,
-    TranslateCommand,
     ValidateCommand,
     ListMilestonesCommand,
     ListIntentsCommand,

skills/scripts/skills/planner/cli/plan_commands.py

@@ -494,8 +494,8 @@ def set_diagram_render(ctx: PlanContext, diagram: str, content_file: str) -> dic
     return {"diagram": diagram, "operation": "updated"}
 
 
-def translate(ctx: PlanContext, output: str) -> dict:
-    """Translate plan.json to Markdown."""
+def _translate(ctx: PlanContext, output: str) -> dict:
+    """Translate plan.json to Markdown. Internal only -- not exposed via CLI."""
     from .plan import translate_to_markdown
 
     plan = ctx.load_plan()

skills/scripts/skills/planner/orchestrator/planner.py

@@ -56,23 +56,28 @@
 MODULE_PATH = "skills.planner.orchestrator.planner"
 
 
-def _translate_plan(state_dir: str) -> None:
+def _translate_plan(state_dir: str) -> str | None:
     """Mechanical translation: plan.json -> plan.md.
 
+    Returns path to plan.md on success, None on failure.
+
     Why non-fatal: plan.json is the source of truth (the IR).
     plan.md is a convenience rendering. If translation fails,
     the workflow should still complete -- QR already approved
     the plan.json content.
     """
     from pathlib import Path
-    from skills.planner.cli.plan_commands import PlanContext, translate
+    from skills.planner.cli.plan_commands import PlanContext, _translate
 
     try:
+        plan_md = str(Path(state_dir) / "plan.md")
         ctx = PlanContext(state_dir=Path(state_dir))
-        translate(ctx, str(Path(state_dir) / "plan.md"))
+        _translate(ctx, plan_md)
+        return plan_md
     except Exception as e:
         import sys
         print(f"Warning: plan.md translation failed: {e}", file=sys.stderr)
+        return None
 
 _provider = PlannerResourceProvider()
 
@@ -225,7 +230,7 @@ def handler(ctx):
     return handler
 
 
-def qr_decompose_step(title, phase, script, mode_total_steps, model=None):
+def qr_decompose_step(title, phase, script, model=None):
     """Steps 4, 8, 12: QR decomposition dispatch.
 
     Dispatches single QR agent to decompose artifact into verification items.
@@ -451,8 +456,7 @@ def handler(ctx):
             "5. CURRENT_UNDERSTANDING: how system works; for bugs: symptom + reproduction",
             "6. ASSUMPTIONS: unverified inferences with confidence H/M/L -- or 'none'",
             "7. INVISIBLE_KNOWLEDGE: design rationale, invariants, accepted tradeoffs",
-            "8. USER_QUOTES: verbatim user statements, especially corrections",
-            "9. REFERENCE_DOCS: paths to project docs sub-agents should read (doc/*.md, specs/*) -- or 'none'",
+            "8. REFERENCE_DOCS: paths to project docs sub-agents should read (doc/*.md, specs/*) -- or 'none'",
             "",
             "FORMAT: High signal-to-noise. File refs over content. No ASCII diagrams.",
             "",
@@ -473,7 +477,6 @@ def handler(ctx):
             '  "current_understanding": ["how system works", "bug: symptom + repro"],',
             '  "assumptions": ["inference (H/M/L confidence)"] or ["none"],',
             '  "invisible_knowledge": ["design rationale", "invariants", "tradeoffs"],',
-            '  "user_quotes": ["verbatim quote with context"],',
             '  "reference_docs": ["doc/spec.md - what it specifies"] or ["none"]',
             "}",
             "",
@@ -485,8 +488,7 @@ def handler(ctx):
             "[ ] 3. At least one constraint OR explicit 'none confirmed'",
             "[ ] 4. Entry points identified OR 'greenfield'",
             "[ ] 5. Someone unfamiliar would understand why we're building this",
-            "[ ] 6. User corrections/quotes preserved verbatim (if any)",
-            "[ ] 7. Reference documentation paths captured or explicit 'none'",
+            "[ ] 6. Reference documentation paths captured or explicit 'none'",
             "",
             "IF ANY CHECK FAILS: gather missing context via AskUserQuestion or exploration.",
         ],
@@ -507,7 +509,6 @@ def handler(ctx):
         title="plan-design-qr-decompose",
         phase="plan-design",
         script="quality_reviewer/plan_design_qr_decompose.py",
-        mode_total_steps=13,
         model="opus",
     ),
     5: qr_verify_step(
@@ -537,7 +538,6 @@ def handler(ctx):
         title="plan-code-qr-decompose",
         phase="plan-code",
         script="quality_reviewer/plan_code_qr_decompose.py",
-        mode_total_steps=13,
         model="opus",
     ),
     9: qr_verify_step(
@@ -568,7 +568,6 @@ def handler(ctx):
         title="plan-docs-qr-decompose",
         phase="plan-docs",
         script="quality_reviewer/plan_docs_qr_decompose.py",
-        mode_total_steps=13,
         model="opus",
     ),
     13: qr_verify_step(
@@ -738,9 +737,12 @@ def main():
         # Why translate on terminal_pass: plan.json is the IR (modified by
         # QR fix cycles). plan.md is a rendered view. Terminal gate approval
         # signals plan.json is stable -- safe to regenerate the markdown.
-        if result.terminal_pass and args.state_dir:
-            _translate_plan(args.state_dir)
         print(result.output)
+        if result.terminal_pass and args.state_dir:
+            plan_path = _translate_plan(args.state_dir)
+            if plan_path:
+                print(f"\nPlan rendered to: {plan_path}")
+                print("Copy this file to the user's requested output path.")
     else:
         print(result)
 

skills/scripts/skills/planner/quality_reviewer/__init__.py

@@ -1,21 +1,8 @@
-"""Quality Reviewer scripts for QR phases.
+"""Quality reviewer modules."""
 
-This package contains:
-- Base classes for decompose and verify workflows
-- Phase-specific QR scripts (plan-design, plan-code, plan-docs, impl-code, impl-docs)
-
-Base classes:
-- DecomposeBase: Shared logic for QR item generation
-- VerifyBase: Shared logic for single-item verification
-
-Scripts extend base classes with phase-specific logic.
-"""
-
-from .qr_decompose_base import DecomposeBase, write_qr_state
-from .qr_verify_base import VerifyBase
+# Export shared utilities from new location
+from .prompts.decompose import write_qr_state
 
 __all__ = [
-    "DecomposeBase",
     "write_qr_state",
-    "VerifyBase",
 ]

skills/scripts/skills/planner/quality_reviewer/impl_code_qr_decompose.py

@@ -1,51 +1,121 @@
 #!/usr/bin/env python3
 """QR decomposition for impl-code phase.
 
-INTENT.md requires separate files per phase.
-This file contains ONLY impl-code-specific item generation.
-Shared logic lives in qr_decompose_base.py.
-
-Impl-code checks:
-- Acceptance criteria verification (factored: expectations vs observations)
-- Cross-cutting concerns (shared state, error propagation)
-- Code quality (all 8 quality documents)
-- Intent marker validation
+Scope: Implemented code quality.
+  - Acceptance criteria verification (expectations vs observations)
+  - Cross-cutting concerns (shared state, error propagation)
+  - Code quality (all 8 quality documents)
+  - Intent marker validation
+NOT plan structure or documentation (verified in earlier phases).
+
+Severity categories: Same as plan-code (Dev can fix code issues).
 """
 
-from .qr_decompose_base import DecomposeBase
+from skills.planner.quality_reviewer.prompts.decompose import dispatch_step
 
 
-class ImplCodeDecompose(DecomposeBase):
-    """QR decomposition for impl-code phase."""
+PHASE = "impl-code"
 
-    PHASE = "impl-code"
 
-    def get_artifact_prompt(self) -> str:
-        """Impl-code reads plan.json and modified files from codebase."""
-        return """Read plan.json from STATE_DIR:
+STEP_1_ABSORB = """\
+Read plan.json from STATE_DIR:
   cat $STATE_DIR/plan.json | jq '.'
 
 Also read MODIFIED_FILES from codebase (paths from milestones).
 
+SCOPE: Implemented code quality.
+
 Focus on:
-  - milestones[].acceptance_criteria
-  - Actual implemented code in modified files
-  - Code quality (structure, patterns, documentation)"""
+  - milestones[].acceptance_criteria (expectations)
+  - Actual implemented code in modified files (observations)
+  - Code quality (structure, patterns, documentation)
+  - Intent markers in implemented code
+
+OUT OF SCOPE:
+  - Plan structure (already verified in plan-design)
+  - Documentation files (impl-docs phase)"""
+
+
+STEP_2_CONCERNS = """\
+Brainstorm concerns specific to IMPLEMENTED CODE:
+  - Acceptance criteria not met
+  - Cross-cutting concerns broken (error handling, logging)
+  - Code quality violations (god objects, god functions)
+  - Missing or invalid intent markers
+  - Implementation drift from plan
+
+DO NOT brainstorm plan structure or documentation concerns."""
 
-    def get_enumeration_guidance(self) -> str:
-        """Return phase-specific enumeration guidance for Step 3."""
-        return """For impl-code, enumerate:
+
+STEP_3_ENUMERATION = """\
+For impl-code, enumerate IMPLEMENTATION ARTIFACTS:
+
+ACCEPTANCE CRITERIA:
   - Each milestone with acceptance_criteria (ID, criteria count)
-  - Files modified per milestone
-  - Cross-cutting concerns mentioned (error handling, logging, etc.)
-  - Code quality aspects to verify"""
+  - Each criterion (ID, expectation text)
+
+FILES:
+  - Files modified per milestone (path list)
+  - Actual file content (read from codebase)
+
+CROSS-CUTTING:
+  - Error handling patterns used
+  - Logging patterns used
+  - Shared state access patterns
+
+CODE QUALITY:
+  - Function sizes (line counts)
+  - Nesting depths
+  - Dependency counts"""
+
+
+STEP_5_GENERATE = """\
+SEVERITY ASSIGNMENT (per conventions/severity.md, impl-code scope):
+
+  MUST (blocks all iterations):
+    - Acceptance criterion not met
+    - MARKER_INVALID: intent marker without valid explanation
+
+  SHOULD (iterations 1-4) - STRUCTURE categories:
+    - GOD_OBJECT: >15 methods OR >10 deps
+    - GOD_FUNCTION: >50 lines OR >3 nesting
+    - CONVENTION_VIOLATION: violates documented project convention
+    - INCONSISTENT_ERROR_HANDLING: mixed exceptions/codes
+
+  COULD (iterations 1-3) - COSMETIC:
+    - DEAD_CODE: unused functions, impossible branches
+    - FORMATTER_FIXABLE: style issues"""
+
+
+COMPONENT_EXAMPLES = """\
+  - A modified file
+  - A milestone's implementation
+  - A cross-cutting concern pattern"""
+
+
+CONCERN_EXAMPLES = """\
+  - Acceptance criteria compliance
+  - Error handling consistency
+  - Code structure quality"""
+
+
+PHASE_PROMPTS = {
+    1: STEP_1_ABSORB,
+    2: STEP_2_CONCERNS,
+    3: STEP_3_ENUMERATION,
+    5: STEP_5_GENERATE,
+}
+
+GROUPING_CONFIG = {
+    "component_examples": COMPONENT_EXAMPLES,
+    "concern_examples": CONCERN_EXAMPLES,
+}
 
 
-def get_step_guidance(step: int, total_steps: int, module_path: str = None, **kwargs) -> dict:
-    """Entry point for workflow execution."""
+def get_step_guidance(step: int, module_path: str = None, **kwargs) -> dict:
     module_path = module_path or "skills.planner.quality_reviewer.impl_code_qr_decompose"
-    decomposer = ImplCodeDecompose()
-    return decomposer.get_step_guidance(step, total_steps, module_path=module_path, **kwargs)
+    state_dir = kwargs.get("state_dir", "")
+    return dispatch_step(step, PHASE, module_path, PHASE_PROMPTS, GROUPING_CONFIG, state_dir)
 
 
 if __name__ == "__main__":