codd-dev 1.7.1__tar.gz → 1.9.2__tar.gz

{codd_dev-1.7.1 → codd_dev-1.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 1.7.1
+Version: 1.9.2
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev
@@ -60,7 +60,7 @@ Description-Content-Type: text/markdown
 pip install codd-dev
 ```
 
-**v1.7.0** — `init` / `scan` / `impact` are stable. `propagate` traces code changes to downstream design docs and doc-to-doc changes via CEG graph. `extract --ai` with baseline preset. Custom `node_id` prefixes via `codd.yaml`. GitHub Action for CI integration.
+**v1.9.0** — `codd implement` now supports **multi-AI engine** (Claude stdout + Codex file-writing) and **automatic parallel execution** within phases via git worktree isolation. Phase milestone format (`#### M1.1`) supported. AI command timeout extended to 1 hour for heavy reasoning models. SWE-bench Verified: **73/73 = 100%** resolved.
 
 ---
 
@@ -132,10 +132,7 @@ done
 codd validate
 
 # Generate code from design docs
-sprints=$(codd plan --sprints)
-for sprint in $(seq 1 $sprints); do
-  codd implement --sprint $sprint
-done
+codd implement
 
 # Assemble code fragments into a buildable project
 codd assemble
@@ -421,6 +418,19 @@ codd impact
 | `codd policy` | **Alpha** | Enterprise policy checker (forbidden/required patterns in source code) |
 | `codd measure` | **Alpha** | Project health metrics (graph, coverage, quality, health score 0-100) |
 | `codd mcp-server` | **Alpha** | MCP server for AI tool integration (stdio, zero dependencies) |
+| `codd fix` | **Alpha** | Auto-fix test/build failures with diagnostic reasoning and session state |
+
+## SWE-bench Verified
+
+CoDD's `fix` command with diagnostic reasoning achieves **73/73 = 100%** on a curated subset of [SWE-bench Verified](https://www.swebench.com/verified.html). The diagnostic step forces root cause analysis before patching, and session state prevents repeating failed approaches across retries.
+
+| Metric | Result |
+|--------|--------|
+| Instances | 73 (curated from SWE-bench Verified) |
+| Resolved | **73 (100%)** |
+| Key feature | Diagnostic reasoning + session state persistence |
+
+Details: [Zenn: CoDD SWE-bench Guide](https://zenn.dev/shio_shoppaize/articles/codd-swebench-pilot?locale=en)
 
 ## OSS / Pro Split
 
@@ -428,7 +438,7 @@ CoDD v1.6.0 introduced a clean OSS/Pro boundary via a bridge pattern.
 
 **OSS (MIT, free)** — everything you need to keep docs coherent:
 
-`init` · `scan` · `impact` · `generate` · `restore` · `propagate` · `extract` · `require` · `plan` · `validate` · `measure` · `policy` · `mcp-server`
+`init` · `scan` · `impact` · `generate` · `restore` · `propagate` · `extract` · `require` · `plan` · `validate` · `measure` · `policy` · `fix` · `mcp-server`
 
 **Pro (private, paid)** — enterprise review and verification:
 

{codd_dev-1.7.1 → codd_dev-1.9.2}/README.md

@@ -22,7 +22,7 @@
 pip install codd-dev
 ```
 
-**v1.7.0** — `init` / `scan` / `impact` are stable. `propagate` traces code changes to downstream design docs and doc-to-doc changes via CEG graph. `extract --ai` with baseline preset. Custom `node_id` prefixes via `codd.yaml`. GitHub Action for CI integration.
+**v1.9.0** — `codd implement` now supports **multi-AI engine** (Claude stdout + Codex file-writing) and **automatic parallel execution** within phases via git worktree isolation. Phase milestone format (`#### M1.1`) supported. AI command timeout extended to 1 hour for heavy reasoning models. SWE-bench Verified: **73/73 = 100%** resolved.
 
 ---
 
@@ -94,10 +94,7 @@ done
 codd validate
 
 # Generate code from design docs
-sprints=$(codd plan --sprints)
-for sprint in $(seq 1 $sprints); do
-  codd implement --sprint $sprint
-done
+codd implement
 
 # Assemble code fragments into a buildable project
 codd assemble
@@ -383,6 +380,19 @@ codd impact
 | `codd policy` | **Alpha** | Enterprise policy checker (forbidden/required patterns in source code) |
 | `codd measure` | **Alpha** | Project health metrics (graph, coverage, quality, health score 0-100) |
 | `codd mcp-server` | **Alpha** | MCP server for AI tool integration (stdio, zero dependencies) |
+| `codd fix` | **Alpha** | Auto-fix test/build failures with diagnostic reasoning and session state |
+
+## SWE-bench Verified
+
+CoDD's `fix` command with diagnostic reasoning achieves **73/73 = 100%** on a curated subset of [SWE-bench Verified](https://www.swebench.com/verified.html). The diagnostic step forces root cause analysis before patching, and session state prevents repeating failed approaches across retries.
+
+| Metric | Result |
+|--------|--------|
+| Instances | 73 (curated from SWE-bench Verified) |
+| Resolved | **73 (100%)** |
+| Key feature | Diagnostic reasoning + session state persistence |
+
+Details: [Zenn: CoDD SWE-bench Guide](https://zenn.dev/shio_shoppaize/articles/codd-swebench-pilot?locale=en)
 
 ## OSS / Pro Split
 
@@ -390,7 +400,7 @@ CoDD v1.6.0 introduced a clean OSS/Pro boundary via a bridge pattern.
 
 **OSS (MIT, free)** — everything you need to keep docs coherent:
 
-`init` · `scan` · `impact` · `generate` · `restore` · `propagate` · `extract` · `require` · `plan` · `validate` · `measure` · `policy` · `mcp-server`
+`init` · `scan` · `impact` · `generate` · `restore` · `propagate` · `extract` · `require` · `plan` · `validate` · `measure` · `policy` · `fix` · `mcp-server`
 
 **Pro (private, paid)** — enterprise review and verification:
 

{codd_dev-1.7.1 → codd_dev-1.9.2}/codd/assembler.py

@@ -1,4 +1,4 @@
-"""CoDD assembler — integrate generated sprint fragments into a working project."""
+"""CoDD assembler — integrate generated fragments into a working project."""
 
 from __future__ import annotations
 
@@ -10,7 +10,7 @@ import warnings
 
 import codd.generator as generator_module
 from codd.generator import _load_project_config, _normalize_conventions
-from codd.implementer import get_task_slugs_by_sprint
+from codd.implementer import get_valid_task_slugs
 from codd.scanner import _extract_frontmatter, build_document_node_path_map
 
 
@@ -51,7 +51,9 @@ def assemble_project(
     prompt = _build_assemble_prompt(config, design_docs, fragments, dest)
 
     # Invoke AI
-    raw_output = generator_module._invoke_ai_command(resolved_ai_command, prompt)
+    raw_output = generator_module._invoke_ai_command(
+        resolved_ai_command, prompt, project_root=project_root,
+    )
 
     # Parse and write files
     files_written = _write_assembled_files(project_root, dest_path, raw_output)
@@ -71,7 +73,6 @@ def _collect_design_documents(project_root: Path, config: dict[str, Any]) -> lis
         full_path = project_root / rel_path
         if full_path.exists():
             content = full_path.read_text(encoding="utf-8")
-            # Strip frontmatter for the prompt
             stripped = _strip_frontmatter(content)
             docs.append({
                 "node_id": node_id,
@@ -82,10 +83,10 @@ def _collect_design_documents(project_root: Path, config: dict[str, Any]) -> lis
 
 
 def _collect_generated_fragments(project_root: Path, config: dict[str, Any]) -> list[dict[str, str]]:
-    """Collect all generated code fragments from src/generated/sprint_N/.
+    """Collect all generated code fragments from src/generated/.
 
-    Cross-references against the implementation plan to detect orphan fragments
-    from renamed or deleted tasks. Orphans are excluded with a warning.
+    Supports both flat layout (src/generated/<task>/) and legacy sprint layout
+    (src/generated/sprint_N/<task>/). Orphan directories are excluded with a warning.
     """
     source_dirs = config.get("scan", {}).get("source_dirs", ["src/"])
     generated_base = None
@@ -101,44 +102,39 @@ def _collect_generated_fragments(project_root: Path, config: dict[str, Any]) ->
     if not generated_base.is_dir():
         return []
 
-    # Load valid task slugs from implementation plan for orphan detection
-    valid_slugs = get_task_slugs_by_sprint(project_root)
+    valid_slugs = get_valid_task_slugs(project_root)
 
     code_extensions = (".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".java", ".css")
     fragments = []
-    for sprint_dir in sorted(generated_base.iterdir()):
-        if not sprint_dir.is_dir() or not sprint_dir.name.startswith("sprint_"):
+
+    orphan_dirs: set[str] = set()
+    if valid_slugs:
+        for child in generated_base.iterdir():
+            if child.is_dir() and not child.name.startswith("sprint_") and child.name not in valid_slugs:
+                orphan_dirs.add(child.name)
+                warnings.warn(
+                    f"Orphan fragment directory 'generated/{child.name}' "
+                    f"does not match any task in the implementation plan. Skipping.",
+                    stacklevel=2,
+                )
+
+    for code_file in sorted(generated_base.rglob("*")):
+        if not code_file.is_file() or code_file.suffix not in code_extensions:
             continue
 
-        # Identify orphan task directories
-        orphan_dirs: set[str] = set()
-        if valid_slugs and sprint_dir.name in valid_slugs:
-            expected = valid_slugs[sprint_dir.name]
-            for child in sprint_dir.iterdir():
-                if child.is_dir() and child.name not in expected:
-                    orphan_dirs.add(child.name)
-                    warnings.warn(
-                        f"Orphan fragment directory '{sprint_dir.name}/{child.name}' "
-                        f"does not match any task in the implementation plan. Skipping.",
-                        stacklevel=2,
-                    )
-
-        for code_file in sorted(sprint_dir.rglob("*")):
-            if not code_file.is_file() or code_file.suffix not in code_extensions:
-                continue
-
-            # Skip files under orphan task directories
-            rel_to_sprint = code_file.relative_to(sprint_dir)
-            if rel_to_sprint.parts and rel_to_sprint.parts[0] in orphan_dirs:
-                continue
-
-            rel_path = code_file.relative_to(project_root)
-            content = code_file.read_text(encoding="utf-8")
-            fragments.append({
-                "sprint_dir": sprint_dir.name,
-                "path": str(rel_path),
-                "content": content,
-            })
+        rel_to_generated = code_file.relative_to(generated_base)
+        if rel_to_generated.parts and rel_to_generated.parts[0] in orphan_dirs:
+            continue
+
+        rel_path = code_file.relative_to(project_root)
+        content = code_file.read_text(encoding="utf-8")
+
+        task_group = rel_to_generated.parts[0] if rel_to_generated.parts else "unknown"
+        fragments.append({
+            "task_group": task_group,
+            "path": str(rel_path),
+            "content": content,
+        })
 
     return fragments
 
@@ -172,13 +168,13 @@ def _build_assemble_prompt(
 ## Instructions
 
 1. Read the design documents below to understand the architecture, component tree, data model, and state management.
-2. Read all generated code fragments — they contain implementation pieces organized by sprint.
+2. Read all generated code fragments — they contain implementation pieces organized by task.
 3. Produce a COMPLETE, BUILDABLE project. This includes:
    - **Project configuration files** at the project root: package.json, tsconfig.json, next.config.*, tailwind.config.*, postcss.config.*, etc. — whatever the tech stack requires to build and run.
    - **Entry point / scaffold files**: app/layout.tsx, app/page.tsx (for Next.js), index.html, main.py, etc. — the files that wire the application together.
    - **Source code** under `{output_dir}/`: components, utilities, types, styles, hooks, reducers.
    - **Style entry points**: globals.css or equivalent with framework imports (e.g. @import "tailwindcss").
-4. Resolve conflicts between sprint fragments: later sprints may refine or replace earlier ones.
+4. Resolve conflicts between fragments: later tasks may refine or replace earlier ones.
 5. Ensure all imports resolve correctly between files.
 6. Do NOT add features beyond what the design documents specify.
 7. Preserve traceability comments (@generated-by, @generated-from) where practical.
@@ -211,11 +207,11 @@ Do not include explanations outside of the === FILE blocks.
 
     # Add generated fragments
     parts.append("## Generated Code Fragments\n")
-    current_sprint = None
+    current_group = None
     for frag in fragments:
-        if frag["sprint_dir"] != current_sprint:
-            current_sprint = frag["sprint_dir"]
-            parts.append(f"\n### {current_sprint}\n")
+        if frag["task_group"] != current_group:
+            current_group = frag["task_group"]
+            parts.append(f"\n### {current_group}\n")
         parts.append(f"#### {frag['path']}\n```\n{frag['content']}\n```\n")
 
     return "\n".join(parts)

{codd_dev-1.7.1 → codd_dev-1.9.2}/codd/cli.py

@@ -491,39 +491,52 @@ def propagate(diff: str, path: str, update: bool, verify: bool, do_commit: bool,
 
 
 @main.command()
-@click.option("--sprint", required=True, type=click.IntRange(min=1), help="Sprint number to implement")
 @click.option("--path", default=".", help="Project root directory")
 @click.option("--task", default=None, help="Generate only one task by task ID or title match")
-@click.option("--clean", is_flag=True, default=False, help="Remove existing sprint output before re-generating")
+@click.option("--clean", is_flag=True, default=False, help="Remove existing generated output before re-generating")
 @click.option(
     "--ai-cmd",
     default=None,
     help="Override AI CLI command (defaults to codd.yaml ai_command or merged CoDD defaults)",
 )
-def implement(sprint: int, path: str, task: str | None, clean: bool, ai_cmd: str | None):
-    """Generate implementation code for a specific sprint."""
-    from codd.implementer import implement_sprint
+def implement(path: str, task: str | None, clean: bool, ai_cmd: str | None):
+    """Generate implementation code from the implementation plan."""
+    from codd.implementer import implement_tasks
 
     project_root = Path(path).resolve()
     codd_dir = _require_codd_dir(project_root)
 
     if clean:
-        click.echo(f"Cleaning src/generated/sprint_{sprint}/ ...")
+        click.echo("Cleaning src/generated/ ...")
 
     try:
-        results = implement_sprint(project_root, sprint, task=task, ai_command=ai_cmd, clean=clean)
+        results = implement_tasks(project_root, task=task, ai_command=ai_cmd, clean=clean)
     except (FileNotFoundError, ValueError) as exc:
         click.echo(f"Error: {exc}")
         raise SystemExit(1)
 
     generated_files = 0
+    failed_tasks = []
     for result in results:
+        if result.error:
+            failed_tasks.append(result)
+            continue
         for generated_file in result.generated_files:
             rel_path = generated_file.relative_to(project_root)
             click.echo(f"Generated: {rel_path} ({result.task_id})")
             generated_files += 1
 
-    click.echo(f"Sprint {sprint}: {generated_files} files generated across {len(results)} task(s)")
+    succeeded = len(results) - len(failed_tasks)
+    click.echo(f"{generated_files} files generated across {succeeded} task(s)")
+
+    if failed_tasks:
+        click.echo(click.style(
+            f"\nFAILED: {len(failed_tasks)} task(s) produced no files:",
+            fg="red", bold=True,
+        ))
+        for ft in failed_tasks:
+            click.echo(click.style(f"  ✗ {ft.task_id} ({ft.task_title}): {ft.error}", fg="red"))
+        raise SystemExit(1)
 
 
 @main.command()
@@ -552,7 +565,7 @@ def assemble(path: str, output_dir: str | None, ai_cmd: str | None):
 
 @main.command()
 @click.option("--path", default=".", help="Project root directory")
-@click.option("--sprint", default=None, type=click.IntRange(min=1), help="Sprint number to verify")
+@click.option("--sprint", default=None, type=click.IntRange(min=1), help="(deprecated, ignored) Sprint number", hidden=True)
 @click.option("--e2e", is_flag=True, default=False, help="Run E2E tests (CI-safe, excludes @cdp-only)")
 @click.option("--deploy", is_flag=True, default=False, help="Run deploy/CDP-only E2E tests against deployed URL")
 @click.option("--base-url", default=None, help="Override BASE_URL for E2E tests")
@@ -902,13 +915,13 @@ def policy(path: str):
 @click.option("--init", "initialize", is_flag=True, help="Generate wave_config from requirement docs")
 @click.option("--force", is_flag=True, help="Overwrite existing wave_config during --init")
 @click.option("--waves", is_flag=True, help="Output only the total wave count (for shell scripting)")
-@click.option("--sprints", is_flag=True, help="Output only the total sprint count (for shell scripting)")
+@click.option("--tasks", is_flag=True, help="Output only the total task count (for shell scripting)")
 @click.option(
     "--ai-cmd",
     default=None,
     help="Override AI CLI command for --init (defaults to codd.yaml ai_command or 'claude --print')",
 )
-def plan(path: str, as_json: bool, initialize: bool, force: bool, waves: bool, sprints: bool, ai_cmd: str | None):
+def plan(path: str, as_json: bool, initialize: bool, force: bool, waves: bool, tasks: bool, ai_cmd: str | None):
     """Show wave execution status from configured artifacts."""
     from codd.planner import build_plan, plan_init, plan_to_dict, render_plan_text
 
@@ -946,7 +959,7 @@ def plan(path: str, as_json: bool, initialize: bool, force: bool, waves: bool, s
 
     if force:
         raise click.BadOptionUsage("force", "--force requires --init")
-    if ai_cmd is not None and not waves and not sprints:
+    if ai_cmd is not None and not waves and not tasks:
         raise click.BadOptionUsage("ai_cmd", "--ai-cmd requires --init")
 
     if waves:
@@ -956,9 +969,9 @@ def plan(path: str, as_json: bool, initialize: bool, force: bool, waves: bool, s
         click.echo(len(wave_config))
         return
 
-    if sprints:
-        from codd.implementer import count_sprints
-        click.echo(count_sprints(project_root))
+    if tasks:
+        from codd.implementer import get_valid_task_slugs
+        click.echo(len(get_valid_task_slugs(project_root)))
         return
 
     try:

{codd_dev-1.7.1 → codd_dev-1.9.2}/codd/fixer.py

@@ -38,6 +38,7 @@ class FixAttempt:
     failures: list[FailureInfo]
     fixed: bool
     ai_output: str = ""
+    diagnosis: str = ""  # root cause diagnosis from this attempt
 
 
 @dataclass
@@ -110,27 +111,35 @@ def run_fix(
             fixed=False,
         )
 
-    # Step 2: Fix loop
+    # Step 2: Fix loop with diagnostic reasoning and session state
     attempts: list[FixAttempt] = []
+    session_state = _SessionState()
+
     for attempt_num in range(1, max_attempts + 1):
         # Map failures to design context
         context = _build_fix_context(project_root, config, failures)
 
-        # Build prompt and invoke AI (fix mode: returns fixed source, writes to files)
-        prompt = _build_fix_prompt(project_root, failures, context, config)
+        # Build prompt with diagnosis step and session state from prior attempts
+        prompt = _build_fix_prompt(
+            project_root, failures, context, config,
+            session_state=session_state,
+        )
         ai_output = _invoke_fix_ai(resolved_ai, prompt, project_root)
 
+        # Extract diagnosis from AI output for session state
+        diagnosis = _extract_diagnosis(ai_output)
+
         # Re-run tests to verify
         new_failures = _run_local_tests(project_root, config)
 
         if new_failures is None:
-            # Tests could not run — mark as unverified, not fixed
             logger.warning("Local tests could not run. Fix is unverified.")
             attempts.append(FixAttempt(
                 attempt=attempt_num,
                 failures=failures,
                 fixed=False,
                 ai_output=ai_output,
+                diagnosis=diagnosis,
             ))
             break
 
@@ -141,11 +150,21 @@ def run_fix(
             failures=failures,
             fixed=fixed,
             ai_output=ai_output,
+            diagnosis=diagnosis,
         ))
 
         if fixed:
             break
 
+        # Accumulate session state for next retry
+        session_state.record_attempt(
+            attempt=attempt_num,
+            diagnosis=diagnosis,
+            failures=failures,
+            new_failures=new_failures,
+            ai_output=ai_output,
+        )
+
         # Next iteration uses new failures
         failures = new_failures
 
@@ -168,6 +187,84 @@ def run_fix(
     )
 
 
+# ---------------------------------------------------------------------------
+# Session state for cross-retry diagnostic context
+# ---------------------------------------------------------------------------
+
+
+class _SessionState:
+    """Accumulates diagnostic context across retry attempts.
+
+    Inspired by SWE-bench diagnose experiment (73/73 = 100%):
+    passing prior attempt history — what was tried, what failed, and why —
+    dramatically reduces wasted retries.
+    """
+
+    def __init__(self) -> None:
+        self.prior_attempts: list[dict[str, str]] = []
+
+    def record_attempt(
+        self,
+        attempt: int,
+        diagnosis: str,
+        failures: list[FailureInfo],
+        new_failures: list[FailureInfo],
+        ai_output: str,
+    ) -> None:
+        summary = {
+            "attempt": str(attempt),
+            "diagnosis": diagnosis[:500],
+            "original_errors": "; ".join(f.summary for f in failures)[:300],
+            "result_after_fix": (
+                "all tests passed" if not new_failures
+                else "; ".join(f.summary for f in new_failures)[:300]
+            ),
+            "approach_summary": _summarize_approach(ai_output)[:500],
+        }
+        self.prior_attempts.append(summary)
+
+    def format_for_prompt(self) -> str:
+        if not self.prior_attempts:
+            return ""
+        lines = ["## Prior attempts (DO NOT repeat these — try a different approach)\n"]
+        for pa in self.prior_attempts:
+            lines.append(f"### Attempt {pa['attempt']}")
+            lines.append(f"- Diagnosis: {pa['diagnosis']}")
+            lines.append(f"- Approach: {pa['approach_summary']}")
+            lines.append(f"- Result: {pa['result_after_fix']}")
+            lines.append("")
+        return "\n".join(lines)
+
+
+def _summarize_approach(ai_output: str) -> str:
+    """Extract a brief summary of what the AI changed from its output."""
+    # Look for explanation text after the last code block
+    parts = ai_output.rsplit("```", 1)
+    if len(parts) > 1:
+        explanation = parts[1].strip()
+        if explanation:
+            return explanation[:500]
+    # Fallback: first 200 chars
+    return ai_output[:200]
+
+
+def _extract_diagnosis(ai_output: str) -> str:
+    """Extract the diagnosis section from AI output."""
+    # Look for ## Diagnosis or ## Root Cause sections
+    for marker in ("## Diagnosis", "## Root Cause", "**Diagnosis:**", "**Root Cause:**"):
+        idx = ai_output.find(marker)
+        if idx >= 0:
+            # Extract until next ## or code block
+            rest = ai_output[idx + len(marker):]
+            end = len(rest)
+            for stop in ("\n## ", "\n```"):
+                pos = rest.find(stop)
+                if pos >= 0 and pos < end:
+                    end = pos
+            return rest[:end].strip()[:500]
+    return ""
+
+
 # ---------------------------------------------------------------------------
 # AI invocation for fix (source-in → fixed-source-out → write back)
 # ---------------------------------------------------------------------------
@@ -613,12 +710,14 @@ def _build_fix_prompt(
     failures: list[FailureInfo],
     design_context: str,
     config: dict[str, Any],
+    *,
+    session_state: _SessionState | None = None,
 ) -> str:
     """Build the prompt for AI to fix failures.
 
-    The prompt includes: error logs, design docs, AND the current source
-    of files mentioned in failures.  The AI returns the complete fixed
-    source for each file in fenced code blocks tagged with file paths.
+    The prompt includes: error logs, design docs, current source of files
+    mentioned in failures, and (on retries) session state from prior attempts.
+    Requires the AI to diagnose root cause BEFORE writing any fix.
     """
     project_name = config.get("project", {}).get("name", project_root.name)
     language = config.get("project", {}).get("language", "unknown")
@@ -635,9 +734,21 @@ def _build_fix_prompt(
     # Collect current source of files mentioned in failures
     source_section = _collect_source_files(project_root, failures)
 
+    # Session state from prior attempts (if retrying)
+    session_section = ""
+    if session_state and session_state.prior_attempts:
+        session_section = session_state.format_for_prompt()
+
     lines = [
         f"You are fixing failures in the project '{project_name}' ({language}).",
         "",
+    ]
+
+    # Insert session state before failures (so AI sees what NOT to repeat)
+    if session_section:
+        lines.extend([session_section, ""])
+
+    lines.extend([
         "## Failures to fix",
         "",
         *failure_section,
@@ -651,9 +762,16 @@ def _build_fix_prompt(
         "",
         "## Instructions",
         "",
-        "1. Read the failing test/build output carefully.",
-        "2. Use the design documents to understand the INTENDED behavior.",
-        "3. Fix the IMPLEMENTATION code to match the design, not the other way around.",
+        "### Step 1: Diagnose (MANDATORY — do this BEFORE writing any fix)",
+        "",
+        "Write a `## Diagnosis` section that answers:",
+        "1. What is the root cause of each failure?",
+        "2. Which file(s) and line(s) are responsible?",
+        "3. What is the correct behavior according to the design docs?",
+        "",
+        "### Step 2: Fix",
+        "",
+        "1. Fix the IMPLEMENTATION code to match the design, not the other way around.",
         "   - If tests fail, fix the source code so tests pass.",
         "   - If a test expects an endpoint/method/feature that doesn't exist in code,",
         "     ADD the missing implementation as described in the design documents.",
@@ -661,15 +779,18 @@ def _build_fix_prompt(
         "   - If build fails (type errors, import errors), fix the source code.",
         "   - If lint fails, fix the lint issues in the source code.",
         "   - If a tool prompted interactively in CI (missing config), create the required config file.",
-        "4. Do NOT modify test files unless the test itself has a bug (e.g., wrong import path).",
-        "5. Do NOT modify design documents.",
-        "6. Make minimal, focused changes. Don't refactor unrelated code.",
-        "7. Follow the target framework's lint rules and naming conventions.",
+        "2. Do NOT modify test files unless the test itself has a bug (e.g., wrong import path).",
+        "3. Do NOT modify design documents.",
+        "4. Make minimal, focused changes. Don't refactor unrelated code.",
+        "5. Follow the target framework's lint rules and naming conventions.",
         "   Avoid using global/reserved names (module, exports, require, etc.) as local variables.",
         "",
         "## Output format (CRITICAL)",
         "",
-        "For each file you fix or create, output the COMPLETE file content in a fenced",
+        "## Diagnosis",
+        "(your root cause analysis here)",
+        "",
+        "Then for each file you fix or create, output the COMPLETE file content in a fenced",
         "code block tagged with the language and the file path (relative to project root):",
         "",
         "```<language> <relative/path/to/file>",
@@ -683,7 +804,7 @@ def _build_fix_prompt(
         "```",
         "",
         "After all code blocks, briefly explain what you fixed and why.",
-    ]
+    ])
 
     return "\n".join(lines)