bugfix

name	bugfix
description	Quality bug fixes (P1/P2). Full TDD cycle, branch from main via feature/, no production deploy.

@bugfix

Quality bug fixes with full TDD cycle. Branch from main via feature/.

When to Use

• P1 (HIGH) or P2 (MEDIUM) issues
• Feature broken but not production
• Reproducible errors

Workflow

1. Read issue — bd show <id> or load from docs/issues/
2. Branch — git checkout main && git pull && git checkout -b fix/{id}-{slug}
3. TDD — Red: failing test → Green: minimal fix → Refactor
4. Quality gates — Run quality gates (see Quality Gates in AGENTS.md)
5. Commit — git commit -m "fix(scope): description"
6. Push — git push -u origin fix/{branch} then gh pr create --base main

Write Plan (F101)

Before modifying any file, emit a write plan:

1. Enumerate — List every file the skill will CREATE / MODIFY / DELETE with a one-line reason (test files and fix files).
2. Flags:
   • --dry-run — Emit write plan only. Do NOT create, modify, or delete any file.
   • --yes — Skip confirmation prompt. Execute immediately. Intended for CI/non-interactive.
3. Confirm — Present the plan to the user and wait for explicit approval (unless --yes).
4. Log — Append write plan event to .sdp/log/events.jsonl (sanitize file paths before logging: strip newlines, ensure valid JSON escaping):

   {"spec_version":"v1.0","event_id":"<uuid>","timestamp":"<ISO-8601>","source":{"system":"sdp-lab","component":"bugfix"},"event_type":"decision.made","payload":{"decision_type":"write_plan","plan":[{"path":"...","action":"CREATE|MODIFY|DELETE","reason":"..."}]},"context":{"feature_id":"<F-id if known>","workstream_id":"<ws-id if applicable>"}}
   

   Include context fields only when the ID is known at plan time. Omit unavailable fields rather than inventing placeholders.

   Note: Phase 1 uses prompt-level write boundaries (CLI out of scope). Aligns with schema/contracts/orchestration-event.schema.json via event_type: "decision.made". Phase 2 CLI will emit natively.

Output format:

WRITE PLAN for @bugfix <target>:
  CREATE: path/to/new/file — <reason>
  MODIFY: path/to/existing/file — <reason>
  DELETE: path/to/removed/file — <reason>

Proceed? [y/n]

Modes:

• No flag: Show plan → Confirm → Execute
• --dry-run: Show plan → STOP
• --yes: Show plan → Execute immediately (no prompt)

Output

Bug fixed, tests added, issue closed, changes pushed.

Recovery

Symptom	Fix
Skill produces no output	Check working directory is project root with docs/workstreams/backlog/
"checkpoint not found"	Run sdp-orchestrate --feature <ID> to create initial checkpoint
"workstream files missing"	Run sdp-orchestrate --index to verify, then @feature to regenerate
Skill hangs / no progress	Check .sdp/log/events.jsonl for last event; use sdp reset --feature <ID> if stuck
Review loop exceeds 3 rounds	Use @review --override "reason", @review --partial, or @review --escalate

See Also

• @hotfix — P0 emergency
• @issue — Classification
• @debug — Root cause analysis