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
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- brainstormingSkill
- caveman-internalSkill
- collaboratingSkill
- design-systemSkill
- executingSkill
- graphify-integrationSkill
- karpathy-guardrailsSkill
- planningSkill
- reviewingSkill
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
- Very specific: line 24
Read all spec files in .forge/specs/.
- Distinctive: line 26
All R-numbered requirements and their acceptance criteria
- Distinctive: line 35
Use keyword matching between the bug description and requirement names/descriptions
- Distinctive: line 36
Use code context: if the bug mentions specific files, endpoints, or functions, grep the spec for those references
- Very specific: line 37
If --from-test was used: read the test source code to understand which feature it tests, cross-reference with spec requirements
- Distinctive: line 39
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.
- Distinctive: line 49
Read the identified requirement's acceptance criteria in full.
- Distinctive: line 72
Write the proposed spec change and get user approval.
- Distinctive: line 76
Missing criterion: Write a new acceptance criterion checkbox to add under the existing requirement.
- Distinctive: line 77
Incomplete criterion: Write a replacement for the vague criterion with specific, testable language.
- Distinctive: line 78
Missing requirement: Write a complete new R-numbered requirement with acceptance criteria.
- Distinctive: line 105
Wait for explicit user approval: Do NOT modify the spec file until the user says yes, approves, or confirms.
- Distinctive: line 111
Write a test that would have caught this bug before it happened.
- Very specific: line 114
If --from-test was used: place the new test near the original test file (same directory or same test suite)
- Distinctive: line 115
If no test file was provided: look at the project's existing test structure (use Glob to find test directories and naming patterns)
- Distinctive: line 118
Write the regression test:
- Distinctive: line 125
Run the regression test to verify it currently fails (proving the bug exists and the test would have caught it):
- Distinctive: line 126
If the test fails: good, this confirms it's a valid regression test
- Distinctive: line 127
If the test passes: the bug may already be fixed, or the test doesn't accurately reproduce the issue.
- Distinctive: line 136
Check if the user wants to verify the fix emerges from the updated spec.
- Very specific: line 138
Read .forge/config.json and check backprop.re_run_after_spec_update.
- Very specific: line 140
If re_run_after_spec_update is true:
- Very specific: line 143
If re_run_after_spec_update is false (or not set):
- Very specific: line 150
If .forge/history/backprop-log.md does not exist, create it with a header:
- Very specific: line 160
Read the existing log and find the highest id: number
- Distinctive: line 161
If the log is empty or new, start at 1
- Distinctive: line 199
If 3 or more backprops share the same pattern category, suggest a systemic change:
- Very specific: line 205
Use the pattern-to-question mapping from references/backprop-patterns.md:
- Distinctive: line 214
If the pattern is "other", suggest the user define a custom question based on the recurring theme.
≈ “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.
Files
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-testmode) - Test file path (optional): Path to the failing test, if
--from-testwas 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.
- 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_reposfield (to know which repos are involved)
- 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?
- 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-testwas used: read the test source code to understand which feature it tests, cross-reference with spec requirements
- 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.
- 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.
- Read the identified requirement's acceptance criteria in full.
- For each criterion, ask: "If this criterion were perfectly implemented and tested, would this bug still have occurred?"
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 - Determine if this is a one-off edge case or a systemic pattern. Check:
- Does
.forge/history/backprop-log.mdexist? If so, read it. - Have similar gaps been logged before? (Same pattern category: input validation, concurrency, error handling, integration)
- Does
- 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.
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.
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}- 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.
- 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.
- Determine the correct test location:
- If
--from-testwas 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_reposfield from the spec and the repo config in.forge/config.jsonto determine which repo the test belongs in
- If
- 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}
- 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.
- 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.
- Read
.forge/config.jsonand checkbackprop.re_run_after_spec_update. - If
re_run_after_spec_updateistrue: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. - If
re_run_after_spec_updateisfalse(or not set):Tip: You can run
/forge execute --filter {spec-domain}to verify the fix emerges from the updated spec alone. Setbackprop.re_run_after_spec_update: truein.forge/config.jsonto enable automatic re-execution after backprop.
Step 6: LOG — Record in backprop log
Append the backpropagation record to the history log.
- If
.forge/history/backprop-log.mddoes not exist, create it with a header:# Backpropagation Log Records of bugs traced back to spec gaps, with corrective actions taken. --- - 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
- Read the existing log and find the highest
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}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 brainstormsessions: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.
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
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.

