Snoozer10/synthesize-skills / .gemini/skills/repo-blast-radius-sync
repo-blast-radius-sync
VerifiedUse when checking code changes for orphaned callers, outdated tests, or stale documentation, discovering change blast radius, or verifying git staged parity against the dependency registry
repo-blast-radius-sync
Overview
- Zero-orphan gate: edits to source, schema, or API must include coupled docs, tests, and callers in staged changes.
- Every change has a blast radius: callers, configs, tests, and docs that must stay in sync.
- Gate
scripts/verify_parity.pyblocks commit when orphans remain;scripts/blast_radius.pydiscovers them pre-flight. Before declaring done:python scripts/verify_parity.py --strictmust exit 0 orERR_ORPHAN_EDIT_VIOLATION/ERR_STALE_REGISTRYin stderr blocks.
When to Use
- Modifying, refactoring, adding features, or fixing bugs in code, scripts, schemas, or configs
- Changing signatures, config keys, or API contracts with downstream callers
- Updating tests or reference docs that may drift from implementation
- When NOT to use: isolated typo with no code coupling, or one-off note outside blast radius
Keywords: orphan-prevention, blast-radius, staged-parity, dependency-graph, doc-coupling, caller-sync, verify_parity, registry-parity
Quick Reference
| Situation | Action |
|---|---|
| Before editing | Run python scripts/blast_radius.py <path> [--json] [--symbol <Func>] and grep ^GOVERNING_DOCS: ^CODE_CALLERS: |
| During edits | Update target plus all coupled files, tests, and docs |
| Before commit | Run python scripts/build_registry.py then python scripts/verify_parity.py --strict [--dry-run] |
| Gate fails (exit 1) | Run python scripts/draft_doc_updates.py <doc> [--dry-run], stage, rebuild and re-verify |
| Need schema? | Load references/registry_schema.json or references/*.example (disclosed) |
| Paths | Always posix a/b.py — \ auto-normalized via as_posix() |
| Live view | Run python scripts/dashboard.py --port 8765 → human http://127.0.0.1:8765 — agent curl http://127.0.0.1:8765/api/status or cat .agent/dashboard.json |
| Optional audit | Append ledger entry if team requires it (see references/) |
Implementation
- Pre-flight discovery
python scripts/blast_radius.py <target_file_path>e.g.python scripts/blast_radius.py src/payments/processor.py- Read checklist categories: CODE CALLERS, GOVERNING DOCS, TEST SUITES, CONFIGS/SCHEMAS
- Cascading mutation
- Edit target file for objective
- Align callers in CODE CALLERS
- Sync keys in CONFIGS/SCHEMAS
- Update pytest cases in TEST SUITES
- Refine manuals in GOVERNING DOCS
- Parity gate and self-healing
- Compile and verify:
python scripts/build_registry.py
python scripts/verify_parity.py --strict
- Exit 0: synchronized, commit allowed
- Exit 1: parse stderr, run
python scripts/draft_doc_updates.py <coupled_doc_path>(e.g.docs/api_reference.md),git adddoc, rebuild registry and re-verify until 0
- Verify runnable check
def blast_radius_contains(radius, expected):
return expected in radius.get("GOVERNING DOCS", []) or expected in radius.get("TEST SUITES", [])
if __name__ == "__main__":
sample = {"GOVERNING DOCS": ["docs/api_reference.md"], "TEST SUITES": ["tests/test_processor.py"], "CODE CALLERS": [], "CONFIGS/SCHEMAS": []}
assert blast_radius_contains(sample, "docs/api_reference.md")
assert not blast_radius_contains(sample, "docs/missing.md")
print("PASS")
Common Mistakes
- Declaring task completed while
verify_parity.pyexits 1. Fix: heal docs and re-verify, do not request review. - Using
# TODO: update documentation laterin code. Fix: update GOVERNING DOCS in same change. - Modifying or deleting
.agent/orscripts/to bypass gate. Fix: keep gate intact, fix orphans. - Guessing doc patches manually. Fix: use
scripts/draft_doc_updates.pyfrom git diff.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |