feat: refresh shared skills catalog
This commit is contained in:
vasily committed
1 parent
98bb35e6fb
commit
418792d1ec
49 files changed
+2273
-2390
No files matched your search
+18
-71
@@ -1,78 +1,25 @@
|
||||
---
|
||||
name: backprop
|
||||
description: >
|
||||
Bug-to-spec feedback loop: when a bug occurs or test fails, traces root cause,
|
||||
adds an invariant (§V) to prevent recurrence, logs to §B, and binds a regression test.
|
||||
Use on test failure during build, user bug report, post-mortem, or when asked to "backprop".
|
||||
concerns: [system-one-balance]
|
||||
Record a meaningful behavioral bug and its prevention in an existing SPEC.md when using the spec workflow or explicitly asked to backprop. Use ordinary debugging for bugs in projects without a spec.
|
||||
scope: global
|
||||
---
|
||||
|
||||
# Backprop — Bug → Spec Feedback Loop
|
||||
# Bug feedback
|
||||
|
||||
Plan-then-execute fixes the code and forgets.
|
||||
Spec-Driven Development fixes the code AND amends the spec so recurrence is impossible.
|
||||
That feedback loop is **backprop**.
|
||||
1. Establish expected behavior and reproduce or otherwise demonstrate the failure.
|
||||
Inspect the cause; use focused debugging probes instead of speculative fixes.
|
||||
2. If `SPEC.md` exists, append a concise §B record. Add or amend a §V invariant
|
||||
only when it expresses a useful behavioral rule not already covered. Preserve
|
||||
monotonically numbered IDs and relevant interface/task references.
|
||||
3. Add regression coverage for the meaningful failure when practical, then apply
|
||||
the smallest fix. For non-automatable failures, preserve reproduction steps and
|
||||
the evidence instead of inventing a test.
|
||||
4. Run the relevant checks under [shared verification](../../protocols/workflow.md#verification).
|
||||
Report the cause, fix, and evidence.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Setup and Protocols
|
||||
|
||||
1. **Governing Invariants**:
|
||||
- Every bug gets a row in the §B table of `SPEC.md`.
|
||||
- Behavioral bugs should be paired with a new §V invariant whenever a rule can prevent recurrence.
|
||||
- A new invariant without an automated test is incomplete: always pin with a test citing the invariant.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Ingest and Check
|
||||
|
||||
1. Parse the failure input: test failure traceback, reproduction log, or user bug report.
|
||||
2. Confirm `SPEC.md` exists; if absent, invoke `spec distill` or create it before logging.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Processing (Core Logic)
|
||||
|
||||
### Step 1: Trace Root Cause
|
||||
- Locate the exact file and line producing the incorrect behavior.
|
||||
- State the root cause in one crisp Caveman sentence.
|
||||
|
||||
### Step 2: Invariant Formulation
|
||||
Evaluate:
|
||||
- Would a testable §V invariant prevent this entire class of bug? (Commonly yes).
|
||||
- Did the interface definition (§I) promise a shape the code cannot deliver?
|
||||
- Was a task (§T) misunderstood or incomplete?
|
||||
|
||||
Draft the proposed additions:
|
||||
```text
|
||||
§B row: B<next>|<date>|<root cause>|V<N>
|
||||
§V line: V<next>: <testable rule that would have caught it>
|
||||
```
|
||||
|
||||
### Step 3: Pin Reproduction Test
|
||||
- Author a failing regression test before modifying application code.
|
||||
- Name the test to cite the invariant: e.g. `test_v7_refund_idempotent()`.
|
||||
|
||||
### Step 4: Implement Fix & Verify
|
||||
- Apply minimal surgical code fix.
|
||||
- Run the regression test to confirm green.
|
||||
- Run the full project test suite to verify no collateral regressions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: The System One Balance Pass
|
||||
|
||||
- **Augment, Don't Handcuff**:
|
||||
- Do NOT invent artificial §V rules for one-off typos or transient external network outages (log in §B, but skip §V).
|
||||
- State invariants positively where possible (`! hold` rather than complex negative conditionals).
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Output Execution & Verification
|
||||
|
||||
Every complete backprop run produces:
|
||||
1. Append to §B table in `SPEC.md`.
|
||||
2. Append to §V invariants (when applicable).
|
||||
3. Passing regression test.
|
||||
4. Minimal code fix.
|
||||
5. Atomic git commit: `backprop §B.<n> + §V.<N>: <one-line cause>`.
|
||||
`backprop` owns §B and bug-related §V amendments. Use `spec` for changes to goals,
|
||||
constraints, or interfaces. Do not create or distill a spec as a prerequisite to a
|
||||
bug fix. If explicitly requested without a spec, provide the feedback record with
|
||||
the fix and explain that no spec was updated. Typos and transient outages need no
|
||||
new invariant, regression test, or mandatory commit.
|
||||
Reference in new issue
Block a user