plan-forge self-repair-reporting.instructions.md

Self-Repair Reporting

When to use: You discovered a defect in Plan Forge itself (plan files, orchestrator, CLI, prompts, instruction files) during execution and worked around it. File a meta-bug so the fix is captured.

---

Two Lanes at a Glance

	Project Bug	Meta Bug (Self-Repair)
What	Bug in the code you're building	Bug in Plan Forge itself
Tool	forge_bug_file / tempering	forge_meta_bug_file
Target repo	Workspace git remote	.forge.json#meta.selfRepairRepo → fallback srnichols/plan-forge
Labels	bug, severity	self-repair, class label

If the defect is in user project code, use forge_bug_file. If the defect is in Plan Forge's own plans, orchestrator, CLI, or prompts — use forge_meta_bug_file.

---

When to Fire forge_meta_bug_file

Fire the tool when you had to work around one of these three defect classes:

1. Plan Defect (plan-defect)

The plan file was wrong. Brittle validation gate, missing scope entry, wrong file path, over-narrow grep pattern, unsatisfiable dependency. You edited the plan or worked around the gate to keep moving.

2. Orchestrator / CLI Defect (orchestrator-defect)

Runtime bug in Plan Forge. Gate timeout too short, spawn failure on Windows, stash not popped after failed retry, estimator recommends a CLI-less model. You worked around it or the retry loop papered over it.

3. Prompt / Template Defect (prompt-defect)

A step-N prompt emitted unsafe output, an instruction file is missing a rule that would have prevented the problem, or a template placeholder wasn't expanded.

---

Worked Examples

Example 1: Brittle grep gate — plan-defect

Phase-28.2 Slice 2 — The plan gate used grep -q 'A' file || grep -q 'B' file but the worker chose identifier isApiOnlyModel, which matched neither pattern. The agent edited the plan gate inline to broaden the match.

{
  "class": "plan-defect",
  "title": "Phase-28.2 Slice 2 gate too narrow for chosen identifier",
  "symptom": "grep gate did not match worker's chosen export name",
  "workaround": "Edited plan gate to accept isApiOnlyModel",
  "slice": "2",
  "plan": "docs/plans/Phase-28.2-PLAN.md"
}