Codegen Debugging Skill Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Create a SEA repo skill that guides agents to debug why code generation fails or produces wrong/incomplete output by tracing the spec→AST→IR→manifest→code pipeline.

Architecture: A single skill with two diagnostic tracks (hard failure vs wrong/incomplete output), aligned with SEA spec-first rules and generator-first guardrails. Keep SKILL.md concise and move detailed checks into a short reference file if needed.

Tech Stack: Markdown skill format with YAML frontmatter; repo-local skill under .claude/skills/.

Task 1: Baseline (RED) — Write failing pressure scenarios

Files:

• Create: .claude/skills/debugging-codegen-pipeline/notes/baseline.md

Step 1: Draft 3+ pressure scenarios

• Include combined pressures (time + sunk cost + ambiguity)
• Scenarios must cover:
  • generator fails (missing outputs / errors)
  • outputs exist but wrong/incomplete
  • temptation to edit generated code

Step 2: Run baseline without skill

• Simulate how an agent responds and record rationalizations verbatim
• Identify failure patterns

Step 3: Summarize violations

• Bullet list of exact failure modes

Task 2: GREEN — Create skill skeleton

Files:

• Create: .claude/skills/debugging-codegen-pipeline/SKILL.md

Step 1: Create YAML frontmatter

• name: debugging-codegen-pipeline
• description: “Use when …” (trigger conditions only, no workflow)

Step 2: Draft core sections

• Overview
• Quick reference table (pipeline stages, tools, expected artifacts)
• Two-track workflow (failure vs mismatch)
• Required sub-skill references
• Common mistakes
• Red flags

Task 3: GREEN — Add reference checklist (optional but likely)

Files:

• Create: .claude/skills/debugging-codegen-pipeline/pipeline-checklist.md

Step 1: Add concise stage-by-stage checks

• Spec validation commands
• AST/IR/manifest verification
• Determinism checks
• Gap report / last-mile steps

Task 4: GREEN — Add one high-quality example

Files:

• Modify: .claude/skills/debugging-codegen-pipeline/SKILL.md

Step 1: Add a single worked example

• Example should show tracing from missing output to a specific spec/flow lint issue

Task 5: REFACTOR — Close loopholes

Files:

• Modify: .claude/skills/debugging-codegen-pipeline/SKILL.md
• Modify: .claude/skills/debugging-codegen-pipeline/notes/baseline.md

Step 1: Add rationalization table Step 2: Add explicit counters for each excuse Step 3: Add red flags list

Task 6: Verify

Files:

• Modify: .claude/skills/debugging-codegen-pipeline/notes/baseline.md

Step 1: Re-run the scenarios with the skill

• Confirm compliance and note any new loopholes

Task 7: Package (optional)

Step 1: If needed, run packaging

• scripts/package_skill.py .claude/skills/debugging-codegen-pipeline