/backpropagation

name: backpropagation
description: Trace runtime bugs back to spec gaps — identify missing acceptance criteria, update specs, generate regression tests, and detect patterns

Backpropagation Skill

You are running the Forge backpropagation workflow. Your job is to trace a runtime bug back to a specification gap, update the spec to close that gap, generate a regression test, and log the correction for systemic pattern detection.

Inputs

You will receive:

• **Bug description**: Natural-language description of the bug, or test failure output + test source code (from `--from-test` mode)
• **Test file path** (optional): Path to the failing test, if `--from-test` was used
• **Test source code** (optional): Contents of the failing test file
• **Spec files**: List of spec files in `.forge/specs/`

Workflow

Step 1: TRACE — Which spec?

Find the spec and requirement that should have prevented this bug.

1. Read all spec files in `.forge/specs/`. For each spec, extract:

• Domain name (from frontmatter)
• All R-numbered requirements and their acceptance criteria
• The `linked_repos` field (to know which repos are involved)

2. Analyze the bug description (and test failure output if available) to determine:

• What component or feature is affected?
• What behavior went wrong?
• What was the expected behavior?

3. Match the bug to the most relevant spec and requirement:

• Use keyword matching between the bug description and requirement names/descriptions
• Use code context: if the bug mentions specific files, endpoints, or functions, grep the spec for those references
• If `--from-test` was used: read the test source code to understand which feature it tests, cross-reference with spec requirements

4. If no spec appears to cover this area at all, note this as a potential "missing requirement" gap and pick the closest spec by domain.

5. Present your finding to the user: > **Traced to:** `spec-{domain}.md` > **R{NNN}: {requirement name}** > **Reasoning:** {why this requirement is the match}

Step 2: ANALYZE — What was missed?

Determine exactly what the spec's acceptance criteria failed to cover.

1. Read the identified requirement's acceptance criteria in full.

2. For each criterion, ask: "If this criterion were perfectly implemented and tested, would this bug still have occurred?"

3. Classify the gap into one of three types:

| Gap Type | Definition | Example | |----------|------------|---------| | **Missing criterion** | The requirement exists but has no criterion covering this case | R001 requires user registration but no criterion tests duplicate email with different casing | | **Incomplete criterion** | A criterion exists but is too vague to catch this edge case | Criterion says "validate email format" but doesn't specify which RFC or edge cases | | **Missing requirement** | No requirement in any spec covers this behavior at all | No spec covers rate limiting, but the bug is a rate limit bypass |

4. Determine if this is a one-off edge case or a systemic pattern. Check:

• Does `.forge/history/backprop-log.md` exist? If so, read it.
• Have similar gaps been logged before? (Same pattern category: input validation, concurrency, error handling, integration)

5. Present the analysis: > **Gap type:** {missing_criterion | incomplete_criterion | missing_requirement} > **What was missed:** {specific description of what the acceptance criteria should have covered} > **Pattern category:** {input_validation | concurrency | error_handling | integration | other}

Step 3: PROPOSE — Spec update

Write the proposed spec change and get user approval.

1. Draft the spec update based on gap type:

• **Missing criterion**: Write a new acceptance criterion checkbox to add under the existing requirement.
• **Incomplete criterion**: Write a replacement for the vague criterion with specific, testable language.
• **Missing requirement**: Write a complete new R-numbered requirement with acceptance criteria. Use the next available R-number in the spec.

2. Present the proposed change clearly, showing before and after:

**For missing criterion:** > **Proposed addition to R{NNN}:** > ``` > - [ ] {New specific, testable criterion} > ```

**For incomplete criterion:** > **Proposed replacement in R{NNN}:** > ``` > Before: - [ ] {old vague criterion} > After: - [ ] {new specific criterion} > ```

**For missing requirement:** > **Proposed new requirement in spec-{domain}.md:** > ```markdown > ### R{NNN}: {Requirement Name} > {Description} > **Acceptance Criteria:** > - [ ] {Criterion 1} > - [ ] {Criterion 2} > ```

3. **Wait for explicit user approval.** Do NOT modify the spec file until the user says yes, approves, or confirms. If the user suggests edits, incorporate them and re-present.

4. Once approved, apply the change to the spec file using the Edit tool. Preserve all existing content — only add or modify the specific criterion/requirement.

Step 4: GENERATE — Regression test

Write a test that would have caught this bug before it happened.

1. Determine the correct test location:

• If `--from-test` was used: place the new test near the original test file (same directory or same test suite)
• If no test file was provided: look at the project's existing test structure (use Glob to find test directories and naming patterns)
• For multi-repo projects: use the `linked_repos` field from the spec and the repo config in `.forge/config.json` to determine which repo the test belongs in

2. Write the regression test:

• **Tests the specific edge case or condition** that caused the bug
• **Follows the project's existing test conventions** (framework, naming, structure)
• **Includes a descriptive test name** that references the bug (e.g., `it('should reject duplicate email with different casing')`)
• **Is minimal** — tests only the specific gap, not a b