agentleFS
LucasDuysLucasDuys/forge/skills/backpropagation/SKILL.md

backpropagation

Skill56 starsChanged 8 months agoMITView on GitHub

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

The file

Show its rules and text

We split this skill into the rules it gives an agent

29 rules. About 0 are common, 20 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈20

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read all spec files in .forge/specs/.

    line 24
  2. Distinctive:

    All R-numbered requirements and their acceptance criteria

    line 26
  3. Distinctive:

    Use keyword matching between the bug description and requirement names/descriptions

    line 35
  4. Distinctive:

    Use code context: if the bug mentions specific files, endpoints, or functions, grep the spec for those references

    line 36
  5. Very specific:

    If --from-test was used: read the test source code to understand which feature it tests, cross-reference with spec requirements

    line 37
  6. Distinctive:

    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.

    line 39
  7. Distinctive:

    Read the identified requirement's acceptance criteria in full.

    line 49
  8. Distinctive:

    Write the proposed spec change and get user approval.

    line 72
  9. Distinctive:

    Missing criterion: Write a new acceptance criterion checkbox to add under the existing requirement.

    line 76
  10. Distinctive:

    Incomplete criterion: Write a replacement for the vague criterion with specific, testable language.

    line 77
  11. Distinctive:

    Missing requirement: Write a complete new R-numbered requirement with acceptance criteria.

    line 78
  12. Distinctive:

    Wait for explicit user approval: Do NOT modify the spec file until the user says yes, approves, or confirms.

    line 105
  13. Distinctive:

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

    line 111
  14. Very specific:

    If --from-test was used: place the new test near the original test file (same directory or same test suite)

    line 114
  15. Distinctive:

    If no test file was provided: look at the project's existing test structure (use Glob to find test directories and naming patterns)

    line 115
  16. Distinctive:

    Write the regression test:

    line 118
  17. Distinctive:

    Run the regression test to verify it currently fails (proving the bug exists and the test would have caught it):

    line 125
  18. Distinctive:

    If the test fails: good, this confirms it's a valid regression test

    line 126
  19. Distinctive:

    If the test passes: the bug may already be fixed, or the test doesn't accurately reproduce the issue.

    line 127
  20. Distinctive:

    Check if the user wants to verify the fix emerges from the updated spec.

    line 136
  21. Very specific:

    Read .forge/config.json and check backprop.re_run_after_spec_update.

    line 138
  22. Very specific:

    If re_run_after_spec_update is true:

    line 140
  23. Very specific:

    If re_run_after_spec_update is false (or not set):

    line 143
  24. Very specific:

    If .forge/history/backprop-log.md does not exist, create it with a header:

    line 150
  25. Very specific:

    Read the existing log and find the highest id: number

    line 160
  26. Distinctive:

    If the log is empty or new, start at 1

    line 161
  27. Distinctive:

    If 3 or more backprops share the same pattern category, suggest a systemic change:

    line 199
  28. Very specific:

    Use the pattern-to-question mapping from references/backprop-patterns.md:

    line 205
  29. Distinctive:

    If the pattern is "other", suggest the user define a custom question based on the recurring theme.

    line 214

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 TypeDefinitionExample
    Missing criterionThe requirement exists but has no criterion covering this caseR001 requires user registration but no criterion tests duplicate email with different casing
    Incomplete criterionA criterion exists but is too vague to catch this edge caseCriterion says "validate email format" but doesn't specify which RFC or edge cases
    Missing requirementNo requirement in any spec covers this behavior at allNo 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:

    ### 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 broad integration test
    • Has a comment referencing the backprop: // Regression: backprop #{N} — {brief description}
  3. Run the regression test to verify it currently fails (proving the bug exists and the test would have caught it):
    • If the test fails: good, this confirms it's a valid regression test
    • If the test passes: the bug may already be fixed, or the test doesn't accurately reproduce the issue. Adjust the test or note this to the user.
  4. Present the test to the user:

    Regression test written: {test file path} Test status: {FAILS as expected / PASSES — bug may be fixed} What it verifies: {description of what the test checks}

Step 5: VERIFY — Optional re-run

Check if the user wants to verify the fix emerges from the updated spec.

  1. Read .forge/config.json and check backprop.re_run_after_spec_update.
  2. If re_run_after_spec_update is true:

    The spec has been updated. You can run /forge execute --filter {spec-domain} to verify that the fix emerges naturally from the updated specification. This will re-execute tasks related to the affected requirement.

  3. If re_run_after_spec_update is false (or not set):

    Tip: You can run /forge execute --filter {spec-domain} to verify the fix emerges from the updated spec alone. Set backprop.re_run_after_spec_update: true in .forge/config.json to enable automatic re-execution after backprop.

Step 6: LOG — Record in backprop log

Append the backpropagation record to the history log.

  1. If .forge/history/backprop-log.md does not exist, create it with a header:
    # Backpropagation Log
    
    Records of bugs traced back to spec gaps, with corrective actions taken.
    
    ---
  2. Determine the next backprop ID:
    • Read the existing log and find the highest id: number
    • If the log is empty or new, start at 1
  3. Append a new entry using the template from templates/backprop-report.md:

    ---
    id: {N}
    date: {YYYY-MM-DD}
    spec: {spec-domain}
    requirement: {R_ID}
    gap_type: {missing_criterion|incomplete_criterion|missing_requirement}
    pattern: {pattern_category}
    ---
    
    # Backprop #{N}
    
    ## Bug Description
    {Original bug description or test failure summary}
    
    ## Root Spec
    - Spec: {spec file path}
    - Requirement: {R_ID}: {requirement name}
    - Gap: {What the acceptance criteria missed}
    
    ## Spec Update
    {The new or modified acceptance criterion that was applied}
    
    ## Regression Test
    - File: {test file path}
    - Verifies: {What the test checks}
    
    ## Pattern
    - Category: {pattern category}
    - Occurrences: {total count of this pattern in the log}
    - Systemic fix suggested: {yes/no}
  4. Pattern detection — After logging, count occurrences of the same pattern category across all entries in the log:

    • If 3 or more backprops share the same pattern category, suggest a systemic change:

    Pattern detected: You've had {N} {pattern_category} gaps. This is a systemic pattern.

    Suggested systemic fix: Add the following as a standard brainstorming question in future /forge brainstorm sessions:

    Use the pattern-to-question mapping from references/backprop-patterns.md:

    Pattern (3+ occurrences)Suggested Brainstorming Question
    input_validation"What are the edge cases for input formats? (unicode, empty, boundary values, special characters)"
    concurrency"What happens with concurrent access? (race conditions, ordering, idempotency)"
    error_handling"What failure modes exist? (network timeout, disk full, rate limit, partial failure)"
    integration"What cross-component contracts exist? (data formats, timing dependencies, versioning)"

    If the pattern is "other", suggest the user define a custom question based on the recurring theme.

Key Principles

  • Trace before fixing — always identify the spec gap before writing code. The spec is the source of truth.
  • User approves spec changes — never modify a spec without explicit approval. The user owns the spec.
  • Regression tests prove the gap — the test must fail before the fix to confirm it would have caught the bug.
  • Patterns drive systemic improvement — individual fixes are good, but identifying patterns makes the whole process better over time.
  • Minimal changes — add only what's needed to close the gap. Don't refactor the entire spec.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.