@haoyiyin/workflow 0.2.2 → 0.2.4

package/src/skills/systematic-debugging/index.ts

@@ -0,0 +1,404 @@
+/**
+ * Systematic Debugging Skill - Find root cause before fixing
+ *
+ * Use case: Bug investigation, test failure, unexpected behavior
+ * Pattern: Reproduce → Gather Evidence → Diagnose (hypothesize + test) →
+ *          Apply Fix → Verify
+ *
+ * CRITICAL RULE: No fix before root cause is confirmed.
+ * Spawns debugger subagent(s) for each phase.
+ * Prevents the "fix-first-ask-questions-later" anti-pattern.
+ */
+
+import { z } from 'zod'
+import { Skill } from '../skill.js'
+import type { SkillContext } from '../types.js'
+import { createDispatcher } from '../../agents/dispatcher.js'
+import { researcherContract } from '../../agents/contracts.js'
+import { createMainAgentGuard } from '../../guard/main-agent.js'
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const DebugInputSchema = z.object({
+  symptom: z.string().min(1, 'Symptom description is required'),
+  reproduceCommand: z.string().optional(),
+  logs: z.string().optional(),
+  recentChanges: z.string().optional(),
+  model: z.string().optional(),
+})
+
+const DebugOutputSchema = z.object({
+  rootCause: z.string(),
+  confidence: z.enum(['high', 'medium', 'low']),
+  location: z.object({
+    file: z.string().optional(),
+    line: z.number().optional(),
+    function: z.string().optional(),
+  }),
+  fixApplied: z.boolean(),
+  fixDescription: z.string().optional(),
+  verification: z.string(),
+  risks: z.array(z.string()),
+  tokensUsed: z.number(),
+})
+
+type DebugInput = z.infer<typeof DebugInputSchema>
+type DebugOutput = z.infer<typeof DebugOutputSchema>
+
+// ---------------------------------------------------------------------------
+// Prompt builders (pure functions)
+// ---------------------------------------------------------------------------
+
+function buildReproducePrompt(
+  symptom: string,
+  reproduceCommand?: string,
+  logs?: string,
+): string {
+  const sections: string[] = [
+    `## Reproduce the Issue`,
+    '',
+    `**Symptom**: ${symptom}`,
+  ]
+  if (reproduceCommand) {
+    sections.push('', `**Command**: \`${reproduceCommand}\``)
+  }
+  if (logs) {
+    sections.push('', '## Logs', '', logs.slice(0, 2000))
+  }
+  sections.push(
+    '',
+    'Confirm reproduction. Report exact steps, observed vs expected.',
+  )
+  return sections.join('\n')
+}
+
+function buildEvidencePrompt(
+  symptom: string,
+  reproOutput: string,
+  recentChanges?: string,
+): string {
+  return [
+    `## Gather Evidence`,
+    '',
+    `**Symptom**: ${symptom}`,
+    '',
+    '## Reproduction',
+    reproOutput.slice(0, 2000),
+    '',
+    recentChanges
+      ? `## Recent Changes\n${recentChanges}`
+      : '## Recent Changes\nCheck git log for related commits.',
+    '',
+    'Identify suspect files, key functions, failure points.',
+    'Trace execution path. Look for error handling gaps, state issues, race conditions.',
+  ].join('\n')
+}
+
+function buildDiagnosePrompt(
+  symptom: string,
+  evidenceOutput: string,
+  knownIssues?: string,
+): string {
+  return [
+    `## Diagnose Root Cause`,
+    '',
+    `**Symptom**: ${symptom}`,
+    '',
+    '## Evidence',
+    evidenceOutput.slice(0, 3000),
+    ...(knownIssues ? ['', '## Known Issues (from research)', knownIssues.slice(0, 1000)] : []),
+    '',
+    '## Process',
+    '1. Form 2-3 hypotheses, rank by likelihood',
+    '2. Test top hypothesis with targeted checks',
+    '3. Eliminate incorrect hypotheses',
+    '4. Confirm root cause with evidence',
+    '',
+    '## CRITICAL: Diagnosis Only — NO Fix Yet',
+    'Do NOT write any code changes in this phase.',
+    'You are confirming the root cause, not fixing it.',
+    '',
+    '## Output Format',
+    '',
+    '```',
+    'Root Cause: <description>',
+    'Confidence: high|medium|low',
+    'File: <path>',
+    'Line: <number>',
+    'Function: <name>',
+    'Evidence: <proof>',
+    'Eliminated: <hypotheses ruled out>',
+    'Fix: <proposed fix description>',
+    '```',
+  ].join('\n')
+}
+
+function buildApplyFixPrompt(diagnosis: {
+  rootCause: string
+  confidence: string
+  file?: string
+  line?: number
+}): string {
+  return [
+    `## Apply Fix`,
+    '',
+    `**Root Cause**: ${diagnosis.rootCause}`,
+    `**Confidence**: ${diagnosis.confidence}`,
+    diagnosis.file ? `**File**: ${diagnosis.file}` : '',
+    diagnosis.line ? `**Line**: ${diagnosis.line}` : '',
+    '',
+    'Apply ONE minimal fix targeting the confirmed root cause.',
+    'Run reproduction test to confirm fix works.',
+    'Do NOT refactor unrelated code.',
+    diagnosis.confidence === 'low'
+      ? 'Low confidence: prefer a safer, more conservative fix.'
+      : '',
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+function buildVerifyPrompt(
+  symptom: string,
+  fixOutput: string,
+): string {
+  return [
+    `## Verify Fix`,
+    '',
+    `**Original**: ${symptom}`,
+    '',
+    '## Fix Applied',
+    fixOutput.slice(0, 2000),
+    '',
+    'Re-run reproduction steps. Run full test suite.',
+    'Return PASS or FAIL with details.',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Parsing helpers (pure functions)
+// ---------------------------------------------------------------------------
+
+interface ParsedDiagnosis {
+  rootCause: string
+  confidence: 'high' | 'medium' | 'low'
+  file?: string
+  line?: number
+  func?: string
+  fixDescription?: string
+}
+
+function parseDiagnosis(output: string): ParsedDiagnosis {
+  const rootCauseMatch = output.match(/root cause:?\s*(.+)/i)
+  const confidenceMatch = output.match(/confidence:?\s*(high|medium|low)/i)
+  const fileMatch = output.match(/file:?\s*(\S+\.\w+)/i)
+  const lineMatch = output.match(/line:?\s*(\d+)/i)
+  const funcMatch = output.match(/function:?\s*(\S+)/i)
+  const fixMatch = output.match(/fix:?\s*(.+)/i)
+
+  let confidence: 'high' | 'medium' | 'low' = 'medium'
+  if (confidenceMatch) {
+    const c = confidenceMatch[1].toLowerCase()
+    if (c === 'high' || c === 'medium' || c === 'low') confidence = c
+  }
+
+  return {
+    rootCause: rootCauseMatch?.[1]?.trim() ?? output.slice(0, 200),
+    confidence,
+    file: fileMatch?.[1]?.trim(),
+    line: lineMatch ? parseInt(lineMatch[1], 10) : undefined,
+    func: funcMatch?.[1]?.trim(),
+    fixDescription: fixMatch?.[1]?.trim(),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Skill class
+// ---------------------------------------------------------------------------
+
+export class SystematicDebuggingSkill extends Skill<DebugInput, DebugOutput> {
+  constructor() {
+    super({
+      name: 'systematic-debugging',
+      description:
+        'Find root cause before fixing. Spawns debugger subagent for systematic diagnosis.',
+      requires: ['tdd'],
+      inputSchema: DebugInputSchema as z.ZodType<DebugInput>,
+      outputSchema: DebugOutputSchema,
+    })
+  }
+
+  async execute(
+    input: DebugInput,
+    context: SkillContext,
+  ): Promise<DebugOutput> {
+    const { config, logger } = context
+    const dispatcher = createDispatcher(logger)
+    const guard = createMainAgentGuard({}, logger)
+    let totalTokens = 0
+
+    guard.activateEmbargo()
+
+    try {
+      // Step 1: Reproduce
+      logger.info(`[debug] Reproducing: ${input.symptom.slice(0, 80)}`)
+      const reproResult = await dispatcher.dispatch(
+        { role: 'debugger', model: input.model || config.defaultModel },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildReproducePrompt(
+            input.symptom,
+            input.reproduceCommand,
+            input.logs,
+          ),
+          owns: [],
+          reads: [],
+        },
+      )
+      totalTokens += reproResult.tokensUsed
+
+      // Step 2: Gather evidence (read-only)
+      logger.info('[debug] Gathering evidence')
+      const evidenceResult = await dispatcher.dispatch(
+        { role: 'explorer', model: input.model || config.defaultModel },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: true,
+            runCommands: false,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildEvidencePrompt(
+            input.symptom,
+            reproResult.output,
+            input.recentChanges,
+          ),
+          owns: [],
+          reads: [],
+        },
+      )
+      totalTokens += evidenceResult.tokensUsed
+
+      // Step 2b: Research known issues (optional)
+      let knownIssuesContext = ''
+      const shouldResearch = /npm|yarn|package|version|error|fail|crash|exception/i.test(input.symptom)
+      if (shouldResearch) {
+        logger.info('[debug] Step 2b: Researching known issues...')
+        const researchResult = await dispatcher.dispatch(
+          { role: 'researcher', model: input.model || config.defaultModel },
+          researcherContract({
+            topic: input.symptom,
+            scope: 'technical',
+            questions: [
+              'Are there known issues or bug reports?',
+              'Any recent breaking changes or deprecations?',
+              'What are common solutions or workarounds?'
+            ],
+            timeRange: '1y'
+          })
+        )
+        totalTokens += researchResult.tokensUsed
+        knownIssuesContext = researchResult.output.slice(0, 1200)
+        logger.info(`[debug] Research complete: ${knownIssuesContext ? 'found known issues' : 'no relevant results'}`)
+      }
+
+      // Step 3: Diagnose (NO FIX YET)
+      logger.info('[debug] Diagnosing root cause (no fix yet)')
+      const diagnoseResult = await dispatcher.dispatch(
+        { role: 'debugger', model: input.model || config.defaultModel },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildDiagnosePrompt(
+            input.symptom,
+            evidenceResult.output,
+            knownIssuesContext,
+          ),
+          owns: [],
+          reads: [],
+        },
+      )
+      totalTokens += diagnoseResult.tokensUsed
+      const diagnosis = parseDiagnosis(diagnoseResult.output)
+
+      // Step 4: Apply fix (only after root cause confirmed)
+      logger.info(
+        `[debug] Applying fix (confidence: ${diagnosis.confidence})`,
+      )
+      const fixResult = await dispatcher.dispatch(
+        {
+          role: 'debugger',
+          model: input.model || config.defaultModel,
+          isolation: 'worktree',
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: true,
+            gitOperations: false,
+          },
+          prompt: buildApplyFixPrompt(diagnosis),
+          owns: diagnosis.file ? [diagnosis.file] : [],
+          reads: [],
+        },
+      )
+      totalTokens += fixResult.tokensUsed
+
+      // Step 5: Verify
+      logger.info('[debug] Verifying fix')
+      const verifyResult = await dispatcher.dispatch(
+        { role: 'verifier', model: input.model || config.defaultModel },
+        {
+          permissions: {
+            readFiles: false,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildVerifyPrompt(input.symptom, fixResult.output),
+          owns: [],
+          reads: [],
+        },
+      )
+      totalTokens += verifyResult.tokensUsed
+
+      return {
+        rootCause: diagnosis.rootCause,
+        confidence: diagnosis.confidence,
+        location: {
+          file: diagnosis.file,
+          line: diagnosis.line,
+          function: diagnosis.func,
+        },
+        fixApplied: fixResult.status === 'success',
+        fixDescription:
+          diagnosis.fixDescription ?? fixResult.output.slice(0, 500),
+        verification: verifyResult.output.slice(0, 500),
+        risks: [],
+        tokensUsed: totalTokens,
+      }
+    } finally {
+      guard.deactivateEmbargo()
+    }
+  }
+}
+
+export const systematicDebuggingSkill = new SystematicDebuggingSkill()
+export default systematicDebuggingSkill

package/src/skills/tdd/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: tdd
+description: Enforce RED/GREEN/REFACTOR TDD cycle with isolated implementer subagents. No implementation before a failing test exists.
+requires: []
+---
+
+## ⛔ MAIN AGENT CONSTRAINT
+
+You are a THIN DISPATCHER. Your ONLY job is to dispatch subagents.
+You MUST NOT: read source files, search code, write/edit files, run tests, run git commands.
+You MAY only: read plan/state files, dispatch subagents via Agent tool, relay results.
+For EVERY user request (including this skill), dispatch a subagent. Never execute yourself.
+
+---
+
+## Use/Exclude Matrix
+
+| Use When | Exclude When |
+|---|---|
+| New feature or behavior implementation | Fixing a typo or formatting (use quick-task) |
+| Bugfix with testable reproduction | Behavior already fully tested |
+| Need confidence via test-first discipline | Exploratory/prototype code |
+| Refactoring that must preserve behavior | Configuration or documentation changes |
+
+## Workflow
+
+1. **RED** — Dispatch implementer subagent (worktree) to write a single failing test. Must confirm test fails for the right reason. If test passes unexpectedly, return INVALID_RED.
+2. **GREEN** — Dispatch implementer subagent (worktree) to write minimal code to pass the test. Code can be hacky; refactor comes next.
+3. **REFACTOR** — Dispatch implementer subagent (worktree) to improve code quality while keeping tests green. No behavior changes allowed.
+4. **Verify** — Dispatch verifier subagent to run full test suite and check for regressions.
+
+## Output Spec
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | enum | `success`, `failure`, `invalid-red` |
+| `phases` | array | RED/GREEN/REFACTOR each with phase, status, command, evidence |
+| `broaderVerification.command` | string | Verification command run |
+| `broaderVerification.result` | enum | `PASS`, `FAIL`, `NOT_RUN` |
+| `filesModified` | string[] | All files changed during TDD cycle |
+| `summary` | string | Human-readable cycle summary |
+| `tokensUsed` | number | Total tokens consumed |
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| RED: test passes unexpectedly | Return status=invalid-red; behavior may already exist |
+| RED: subagent fails | Return status=failure with phase evidence |
+| GREEN: subagent fails | Return status=failure; preserve RED phase results |
+| REFACTOR: subagent fails | Record phase as skipped; return success if GREEN passed |
+| Verifier reports regressions | Return broaderVerification.result=FAIL |