📦 deps(skills): sync thirdparty skills
This commit is contained in:
ci[bot]
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: brooks-sweep
|
||||
description: >
|
||||
Full-sweep mode: runs a unified analysis across all quality dimensions — code decay,
|
||||
architecture, tech debt, and test quality — then applies fixes directly to the
|
||||
codebase. Safe changes are auto-applied; risky changes are confirmed before
|
||||
execution. Drawing on twelve classic engineering books.
|
||||
Triggers when: user wants to "fix everything", "sweep the codebase", "auto-fix all
|
||||
issues", "run all checks and fix them", "clean up the whole project", or asks for
|
||||
a single command that both diagnoses and remediates quality problems.
|
||||
Do NOT trigger for: read-only audits or health reports where the user only wants
|
||||
findings without code changes; single-dimension reviews (use the focused skill
|
||||
instead: brooks-review / brooks-audit / brooks-debt / brooks-test); server health
|
||||
checks, HTTP /health endpoints, Kubernetes probes, or application uptime.
|
||||
---
|
||||
|
||||
# Brooks-Lint — Full Sweep & Auto-Fix
|
||||
|
||||
## Setup
|
||||
|
||||
1. Read `../_shared/common.md` for the Iron Law, Project Config, Report Template, and Health Score rules
|
||||
2. Read `../_shared/source-coverage.md` for book-level coverage, exceptions, and tradeoffs
|
||||
3. Read `../_shared/decay-risks.md` for production risk symptom definitions
|
||||
4. Read `../_shared/test-decay-risks.md` for test risk symptom definitions
|
||||
5. Read `sweep-guide.md` in this directory for the unified scan and fix process
|
||||
|
||||
## Process
|
||||
|
||||
**If the user has not specified a project or directory:** apply Auto Scope Detection
|
||||
from `../_shared/common.md` to determine the review scope before proceeding.
|
||||
|
||||
1. Show pre-flight consent notice and wait for the user's one-time approval (Step 0 of the guide)
|
||||
2. Enumerate scope and initialize the `unresolvable` / `non_critical_rounds` / `fix_log` state (Step 1 of the guide)
|
||||
3. Run the four dimensions in sequence — review, test, debt, audit — each scanning, classifying, applying Safe + Extended-Safe fixes, and verifying via the project test command (Steps 2–5 of the guide)
|
||||
4. Iterate: re-scan modified files + same-module + static consumers; converge on a clean round, retire 3-retry failures to the `unresolvable` set, cap non-critical rounds at 3 (Step 6 of the guide)
|
||||
5. Aggregate residual and unresolvable items and output the Full Sweep Report (Steps 7–8 of the guide)
|
||||
|
||||
**Mode line in report:** `Full Sweep`
|
||||
+264
@@ -0,0 +1,264 @@
|
||||
# Brooks-Lint — Full Sweep Guide
|
||||
|
||||
Sequential autonomous pipeline: **review → test → debt → audit**. Fixes findings
|
||||
in place, iterates until clean or capped, reports residuals. One interaction point:
|
||||
Step 0 (pre-flight consent) — after approval the pipeline runs hands-free until Step 8.
|
||||
|
||||
Every finding follows the Iron Law: **Symptom → Source → Consequence → Remedy**.
|
||||
|
||||
---
|
||||
|
||||
### Step 0 — Pre-flight consent gate
|
||||
|
||||
**Goal:** State scope, cost, and irreversibility up front; get explicit consent
|
||||
once so later steps never have to ask.
|
||||
|
||||
0a. Estimate the file count using `git ls-files | wc -l` if in a git repo, or
|
||||
`find . -type f -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/build/*' -not -path '*/dist/*' -not -path '*/vendor/*' -not -path '*/target/*' | wc -l` otherwise. Order-of-magnitude is enough.
|
||||
|
||||
0b. Show this notice verbatim with the estimate filled in. Do not paraphrase —
|
||||
the user is agreeing to this exact scope.
|
||||
|
||||
```
|
||||
⚠️ /brooks-sweep — Full Repository Sweep & Auto-Fix
|
||||
|
||||
Scope: Four analysis dimensions run in sequence — PR code decay (R1–R6),
|
||||
test quality (T1–T6), tech debt, architecture. Edits are made in
|
||||
place inside the detected project scope.
|
||||
Estimated files in scope: ~N
|
||||
|
||||
Order: brooks-review → brooks-test → brooks-debt → brooks-audit.
|
||||
Each dimension scans, queues, and fixes before the next starts.
|
||||
|
||||
Autonomy: Fully autonomous. Safe single-file fixes apply directly. Multi-file
|
||||
fixes that have test coverage AND do not break a public interface
|
||||
also apply directly. High-risk fixes (public API break, cross-module
|
||||
structural change, or no test coverage) are NOT applied — they are
|
||||
recorded in the residual report for human review.
|
||||
|
||||
Iteration: After each dimension pass, modified files + same-module + static
|
||||
consumers are re-scanned. A finding that fails to fix 3 times is
|
||||
retired to the unresolvable set and never re-queued. Non-critical
|
||||
rounds cap at 3 iterations; critical findings iterate until
|
||||
resolved or retired.
|
||||
|
||||
Git impact: The pipeline edits files. It does NOT commit, push, or amend.
|
||||
If you have uncommitted work you want to preserve, commit or stash
|
||||
first.
|
||||
|
||||
Proceed with full autonomous sweep? [Y/n]
|
||||
```
|
||||
|
||||
0c. Parse the reply (first match wins, evaluate rules in order):
|
||||
1. **Hard negation** (`no`, `n`, `abort`, `cancel`, `取消`, `不要`): abort with "Aborted before scan — no files modified."
|
||||
2. **Consent** (`Y`, `yes`, `ok`, `sure`, `proceed`, `go`, `continue`, `好`, `好的`, `行`, `可以`): proceed to Step 1.
|
||||
3. **Soft pause** (`wait`, `hold on`, `等一下`, `等我`, `let me`): acknowledge in one line ("Understood, waiting"), then wait for the user's next message and re-evaluate from rule 1.
|
||||
4. **Question**: answer it, then re-show the notice once and wait for the next reply. If the next reply is not Consent (rule 2) — whether a second question, another pause, or anything else — abort with "Aborted — did not receive consent after clarification."
|
||||
|
||||
0d. After consent, do not ask further questions until Step 8.
|
||||
|
||||
---
|
||||
|
||||
### Step 1 — Scope enumeration and state init
|
||||
|
||||
1a. Apply Auto Scope Detection from `../_shared/common.md` if the user did not
|
||||
specify files or a directory. Otherwise honor the user's explicit scope.
|
||||
|
||||
1b. Read `.brooks-lint.yaml` from the project root if present. Apply `disable`,
|
||||
`severity`, `ignore`, `focus`, and `custom_risks` per common.md. Record the
|
||||
applied config values and reuse them across all iteration rounds — do not
|
||||
re-read the file in Step 6 even if files were modified.
|
||||
|
||||
1c. Initialize pipeline state (persists across all rounds):
|
||||
|
||||
- **`unresolvable`** (set): findings retired after 3 failed attempts — keyed by `(file, line_range, risk_code)`; `signature` breaks ties. Never re-queued.
|
||||
- **`non_critical_rounds`** (int, 0): incremented each round producing Warning/Suggestion; reset on clean round.
|
||||
- **`fix_log`** (list): each fix with file, line range, risk code, description, and outcome (`applied` / `reverted` / `retired`).
|
||||
|
||||
1d. Record the final scope file list in the Fix Report output buffer for Step 8.
|
||||
|
||||
---
|
||||
|
||||
### Step 2 — brooks-review pass (R1–R6 code decay)
|
||||
|
||||
Scan every file in scope against all R-series risks defined in
|
||||
`../_shared/decay-risks.md`.
|
||||
|
||||
2a. For each R-risk, apply its symptom checklist. Record each hit as a finding
|
||||
with: risk code, file + approximate line range, Symptom, Source,
|
||||
Consequence, Remedy, Severity (Critical / Warning / Suggestion), and
|
||||
**Fix-Class** (see Step 2b).
|
||||
|
||||
2b. Assign Fix-Class per finding:
|
||||
|
||||
| Class | Criteria |
|
||||
|-------|----------|
|
||||
| **Safe** | Single-file AND fully local: rename a non-exported symbol, extract a constant, remove dead code, add a null guard at a leaf, add a test scaffold for an untested pure function. Any change that modifies or removes an exported symbol is NOT Safe even if in one file. |
|
||||
| **Extended-Safe** | Multi-file but (a) a project test command exists and passes pre-fix, AND (b) the change does not rename, remove, or alter the signature of any publicly exported symbol, AND (c) touches ≤ 5 files in this pass. |
|
||||
| **Residual** | Public API break, cross-service boundary change, no test coverage to fall back on, or remedy ambiguous. NOT applied — carried to the Step 8 residual report. |
|
||||
|
||||
2c. Skip any finding that matches an entry in the `unresolvable` set.
|
||||
|
||||
2d. Apply every Safe and Extended-Safe fix in this dimension, lowest risk
|
||||
within each severity tier first. For each fix: Edit or Write, then append
|
||||
one row to `fix_log` with outcome `applied`. If two fixes touch overlapping
|
||||
line ranges in the same file, apply higher-severity first, re-read the file,
|
||||
then apply the next.
|
||||
|
||||
2e. After all fixes in this dimension, run the project test/lint command if one
|
||||
exists (`package.json` scripts, `pytest`, `cargo test`, `go test ./...`, etc.).
|
||||
If tests fail: revert fixes from this dimension in reverse order one at a
|
||||
time, re-running the test command after each revert, until tests pass.
|
||||
Mark each reverted fix with outcome `reverted` in `fix_log` and promote the
|
||||
finding to **Residual**. If no test command is found, note this once in the
|
||||
report and continue.
|
||||
|
||||
2f. Record dimension summary: N scanned, M Safe applied, K Extended-Safe applied,
|
||||
R reverted, P Residual.
|
||||
|
||||
---
|
||||
|
||||
### Step 3 — brooks-test pass (T1–T6 test decay)
|
||||
|
||||
Scan test files (and untested production code) against T-series risks defined
|
||||
in `../_shared/test-decay-risks.md`.
|
||||
|
||||
Follow the same sub-steps as Step 2 (classify → apply → verify → summarize),
|
||||
using T-prefix risk codes. For production files with no test coverage at all,
|
||||
record as T2 (Missing Tests). A test scaffold that adds a pure-function test is
|
||||
**Safe**; adding tests that require new test infrastructure is **Residual**.
|
||||
|
||||
---
|
||||
|
||||
### Step 4 — brooks-debt pass (tech debt accumulation)
|
||||
|
||||
Re-classify R-findings through a debt lens — same symptoms at accumulation scale:
|
||||
repeated duplication, layered workarounds, stale `TODO`/`FIXME` clusters, dead
|
||||
flags. Score each with **Pain (1–3) × Spread (1–3)**; total 7–9 = Critical,
|
||||
4–6 = Warning, 1–3 = Suggestion. Apply a severity bump for pattern-level
|
||||
occurrences (isolated Suggestion → 4+ modules Warning).
|
||||
|
||||
Follow the same sub-steps as Step 2. Debt findings often span multiple files
|
||||
and are more likely to land in Extended-Safe or Residual than Safe.
|
||||
|
||||
---
|
||||
|
||||
### Step 5 — brooks-audit pass (architecture integrity)
|
||||
|
||||
Scan the full scope for architecture-level issues. The dependency-direction
|
||||
symptoms (inverted dependencies, circular imports, cross-domain coupling) are
|
||||
defined in `../_shared/decay-risks.md` Risk 5 — use that checklist. Step 5
|
||||
additionally covers architecture-only concerns that R5 does not: missing
|
||||
abstraction layers, god modules, leaked infrastructure inside domain code,
|
||||
and seam-boundary violations.
|
||||
|
||||
Most architecture findings are **Residual** by definition — they require human
|
||||
judgment on module boundaries. A few are Extended-Safe (e.g. extract a shared
|
||||
constant used in 3+ modules into a new module that nothing else imports yet).
|
||||
Do not auto-refactor module layouts, rename packages, or change public exports.
|
||||
|
||||
Follow the same sub-steps as Step 2.
|
||||
|
||||
---
|
||||
|
||||
### Step 6 — Iteration loop
|
||||
|
||||
**Goal:** Re-scan what the fixes touched and converge. Stop on clean round,
|
||||
cap, or no progress.
|
||||
|
||||
6a. Build the re-scan scope:
|
||||
- every file modified in Steps 2–5 of the current round, PLUS
|
||||
- every file in the same module as a modified file, PLUS
|
||||
- every file that statically imports from a modified file.
|
||||
|
||||
Do not re-scan files whose dependencies were not touched. On monorepos
|
||||
where a "module" may span hundreds of files, narrow the same-module bucket
|
||||
to files that import from or are imported by a modified file (direct
|
||||
dependency graph only).
|
||||
|
||||
6b. Re-run Steps 2–5 on the re-scan scope. For each new finding in this round:
|
||||
- If it matches an entry in `unresolvable` → skip.
|
||||
- Else if 🔴 Critical → queue and fix; Critical findings iterate until
|
||||
resolved OR retired (3 failed attempts → `unresolvable`).
|
||||
- Else 🟡 Warning / 🟢 Suggestion → queue and fix, subject to cap below.
|
||||
|
||||
6c. Classify the round after all fixes attempted:
|
||||
- **Clean round** (no new findings outside `unresolvable`): pipeline
|
||||
converged → proceed to Step 7.
|
||||
- **Critical-only round**: do NOT increment `non_critical_rounds`; return
|
||||
to 6a.
|
||||
- **Mixed or non-critical round** (any Warning / Suggestion produced):
|
||||
increment `non_critical_rounds` by 1. If it reaches the cap (default 3,
|
||||
or `sweep.max_iterations` from `.brooks-lint.yaml`), proceed to Step 7
|
||||
with remaining non-critical findings recorded as
|
||||
`"Unresolved — iteration cap reached"`. Otherwise return to 6a.
|
||||
|
||||
6d. Fix-retry rule: if a single finding fails verification (Step 2e) 3 times
|
||||
across any combination of rounds, retire it to `unresolvable` with reason
|
||||
`"3-retry budget exhausted"` and stop attempting it.
|
||||
|
||||
---
|
||||
|
||||
### Step 7 — Residual aggregation
|
||||
|
||||
Collect everything that was NOT fixed in place, de-duplicated:
|
||||
|
||||
- All Residual-class findings from Steps 2–5 (first round + re-scan rounds)
|
||||
- All `unresolvable` entries with their retirement reason
|
||||
- All iteration-cap residuals from Step 6c
|
||||
|
||||
Sort Critical → Warning → Suggestion. Within each severity, list file path,
|
||||
risk code, Symptom (one line), Remedy (one line), and the reason it was not
|
||||
applied (`public API break` / `no test coverage` / `3-retry budget` /
|
||||
`iteration cap`).
|
||||
|
||||
---
|
||||
|
||||
### Step 8 — Sweep report
|
||||
|
||||
Output the final report. Use the standard Report Template from
|
||||
`../_shared/common.md` with these additions:
|
||||
|
||||
```
|
||||
# Brooks-Lint — Full Sweep Report
|
||||
Mode: Full Sweep | Scope: <files or directory>
|
||||
Config: .brooks-lint.yaml applied (N risks disabled, M paths ignored) # omit if no config
|
||||
|
||||
## Dimension Summary
|
||||
| Dimension | Scanned | Safe Applied | Extended Applied | Reverted | Residual |
|
||||
|-----------|---------|--------------|------------------|----------|----------|
|
||||
| Review (R1–R6) | ... | ... | ... | ... | ... |
|
||||
| Test (T1–T6) | ... | ... | ... | ... | ... |
|
||||
| Debt | ... | ... | ... | ... | ... |
|
||||
| Audit | ... | ... | ... | ... | ... |
|
||||
|
||||
## Iteration History
|
||||
Round 1: <classification — clean / critical-only / mixed>, <N> new findings
|
||||
Round 2: ...
|
||||
Stopped at: clean round | iteration cap | no outstanding criticals
|
||||
|
||||
## Fix Log
|
||||
| # | File | Lines | Risk | Outcome | Change |
|
||||
|---|------|-------|------|----------|--------|
|
||||
| 1 | ... | ... | R2 | applied | Extract repeated constant |
|
||||
| 2 | ... | ... | T4 | reverted | Test regression; promoted to Residual |
|
||||
...
|
||||
|
||||
## Health Score Delta
|
||||
Before: <estimated score>/100 → After: <estimated score>/100
|
||||
(Re-run /brooks-health for an exact recalculation.)
|
||||
|
||||
## Residual Items (<K> not applied)
|
||||
<Iron Law entries, sorted Critical → Suggestion, with "Not applied because: ..." line>
|
||||
|
||||
## Summary
|
||||
- Total findings detected: <N>
|
||||
- Fixed this sweep: <M>
|
||||
- Residual (needs human review): <K>
|
||||
- Unresolvable (3-retry exhausted): <U>
|
||||
```
|
||||
|
||||
If there are zero residual items and zero unresolvable entries, end with:
|
||||
**"Sweep complete — codebase is clean."**
|
||||
|
||||
**Mode line in report:** `Full Sweep`
|
||||
Reference in New Issue
Block a user