sova-health-audit
Skill3 starsChanged 2 days agoApache-2.0View on GitHub
Deep technical health audit (architecture, modules, files, functions). Scored, prioritized, actionable.
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- dashboard-designSkill
- database-patternsSkill
- design-systemSkill
- design-tasteSkill
- issue-templateSkill
- sova-address-prSkill
- sova-after-mergeSkill
- sova-agent-readinessSkill
- sova-audit-instructionsSkill
- sova-debugSkill
- sova-develop-explainSkill
- sova-develop-fullSkill
- sova-developSkill
- sova-extract-knowledgeSkill
- sova-find-taskSkill
- sova-ingest-reviewSkill
- sova-integrate-prSkill
- sova-issueSkill
- sova-new-featureSkill
- sova-optimize-knowledgeSkill
- sova-prSkill
- sova-rearrange-commitsSkill
- sova-researchSkill
- sova-review-fullSkill
- sova-review-prSkill
- sova-reviewSkill
- sova-simplifySkill
- sova-specSkill
- sova-standupSkill
- sova-statusSkill
- sova-testSkill
- sova-update-docsSkill
- testing-patternsSkill
- visual-auditSkill
- dashboard-designSkill
- database-patternsSkill
- design-tasteSkill
- issue-templateSkill
- testing-patternsSkill
- visual-auditSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
31 rules. About 0 are common, 19 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈19
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 71
All closed, no carry-over groups: delete the file, tell the user the previous cycle is complete, and run a full audit.
- Very specific: line 73
All closed, carry-over groups present: do not delete. List them, capture their findings, record them as carry-over groups, and run a full …
- Very specific: line 87
Read these in order, skipping any that do not exist: AGENTS.md, CLAUDE.md and .claude/rules/*.md.
- Very specific: line 100
Run the project's checks to verify current health: make test, make lint, and make check when the project has one single CI-equivalent …
- Distinctive: line 107
Use the mode recorded in Step 1.
- Distinctive: line 137
Agent C, Testing, Dependencies and Operations: test quality and coverage gaps, dependency health, CI/CD quality, operational readiness …
- Distinctive: line 159
Budget rule: if verification cannot finish before the context runs out, drop every finding whose claims were not reached, from the report …
- Distinctive: line 168
Only use labels and milestones that exist in the project:
- Very specific: line 175
If a label is missing, create it with gh label create or use the closest existing one.
- Very specific: line 176
If the target milestone is missing, create it with gh api repos/:owner/:repo/milestones -X POST -f title="<name>" before Phase C.
- Very specific: line 241
Write the full audit to docs/HEALTH-AUDIT.md as a local work artifact.
- Distinctive: line 249
Put this at the very top of the file, before the title:
- Very specific: line 263
Phase A: write withheld=, deferred= and the open-target folded= entries verbatim as the carry-over set Step 1 surfaced.
- Distinctive: line 290
Run this before the general confirmation below.
- Very specific: line 308
public-policy <path>: read the policy and quote its private reporting instructions (advisory link, email, form) in the Withhold option of … - Very specific: line 311
public-no-policy: ask the same question without a policy quote. - Very specific: line 332
If the choice is "Withhold" or "File neutrally", check the Step 1 report path verdict before accepting it.
- Distinctive: line 397
When an open issue already covers a group's files for the same concern, the group is
- Distinctive: line 406
After creation, report all issue numbers and which groups were folded, left deferred, filed neutrally or withheld.
- Distinctive: line 427
Only now, after the confirmation, post each folded group's findings on its target (a "file neutrally" group without the exploit path):
- Distinctive: line 447
Only issues created in this run: a fold target is someone else's issue, never added.
- Distinctive: line 471
After creating issues, verify:
- Very specific: line 484
Every "withhold" group has no issue and is in withheld=.
- Distinctive: line 485
Every "file neutrally" issue body has no exploit-path specifics.
- Distinctive: line 486
Every folded group's findings are commented on its target issue.
- Very specific: line 487
Every carry-over group ended in exactly one of three states: filed (has an issue or fold target, in neither field), still withheld or …
- Distinctive: line 493
Do NOT fabricate findings.
- Distinctive: line 494
Do NOT pad the report with generic advice.
- Distinctive: line 495
Do NOT soften critical findings.
- Distinctive: line 496
Keep the report actionable: 30 well-prioritized findings beat a 200-finding dump.
- Distinctive: line 498
Before creating issues, show the grouping and ask for confirmation.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Deep Technical Health Audit
Focus area: the arguments provided when this skill is invoked
Role
You are the original architect and sole developer of this application, a senior engineer with 20 years of experience who knows every design decision, shortcut and deferred TODO. Produce an honest, thorough health report for (a) onboarding a new senior engineer, (b) a due-diligence review, and (c) your own improvement backlog.
Be brutally honest: flag what is genuinely good (so it is preserved) and what is weak (so it can be fixed). Every finding must reference concrete code, files, or patterns in THIS codebase. No generic advice.
Procedure
Step 1: Staleness check
Report path safety: first, whether or not docs/HEALTH-AUDIT.md exists yet, run:
sova audit report-pathRecord the verdict for Phase C. It blocks only a "withhold" or "file neutrally" choice, never the audit itself:
safe: the path is gitignored. No action.unsafe-untracked: warn now that withheld or neutrally filed exploit detail would land in a file git can commit; suggest addingdocs/HEALTH-AUDIT.mdto.gitignore. Continue.unsafe-tracked: same warning. Do not untrack it now: only a Withhold or File neutrally choice makes Phase C rungit rm --cached. Continue.unsafe-not-a-git-repo: state that the path has no git protection. Phase C's block must ask for a different, protected path, not a.gitignoreedit. Continue.
The verdict is the last line printed; a failed call or any other last line counts as
unsafe-untracked.
Next, check whether docs/HEALTH-AUDIT.md already exists. If it does, read its
audit-tracker comment. List the open issues once, then look up only the tracked
numbers (issues= and the folded= targets) that call did not return:
gh issue list --state open --limit 1000 --json number --jq '.[].number'
gh issue view <n> --json state --jq .stateA number whose lookup fails (deleted, transferred, or an API error) is reported as
could not verify #N, counted as neither open nor closed, and the user is asked once
whether to treat it as closed.
A withheld group (the withheld= field, see Phase A) has no issue number, so it never
appears in that comparison. It is still open work: record it as a carry-over group,
which Phase C's pre-flight re-asks instead of resolving silently. So is a deferred=
group, and a folded= group whose target is closed: a closed fold target proves
nothing about the folded findings. An open fold target is informational: list it, never
count it as "still open". Before anything
overwrites the report, capture each carry-over group's verbatim finding blocks (the
#### [P{n}] {title} blocks under "Findings by Level") into this run's working state,
keyed by slugified group name. Phase C renders a carry-over group from that capture,
because by the time Phase C executes, Phase A has already overwritten the file.
Compare against the tracked issues= numbers (created issues only):
- All closed, no carry-over groups: delete the file, tell the user the previous cycle is complete, and run a full audit.
- All closed, carry-over groups present: do not delete. List them, capture
their findings, record them as carry-over groups, and run a full audit (the
withheld carry-over does not make this an incremental run); record mode =
full. Phase A rewrites the file, so each carry-over group's name and findings must reach its header; an unresolved carry-over group is never silently dropped. - Some still open: warn that N issues from the previous audit are still open, list
them, and ask the user to choose Full audit (overwrite with a fresh analysis),
Incremental audit (re-analyze only areas changed since the last audit, preserving
still-open findings elsewhere), or Abort. If
withheld=is present, also list and capture every carry-over group, whichever mode is picked. Record the mode (fullorincremental): Step 4 depends on it.
Step 2: Discover the project
Read these in order, skipping any that do not exist: AGENTS.md, CLAUDE.md and
.claude/rules/*.md; README.md; architecture docs (docs/architecture.md,
docs/ARCHITECTURE.md, ARCHITECTURE.md); coding standards (CONTRIBUTING.md,
.editorconfig, linter configs); the manifest (pyproject.toml, package.json,
Cargo.toml, go.mod); the top-level directory listing.
Note the project's purpose, tech stack, scale, stage (prototype to mature), key domains, and architecture patterns.
Collect codebase stats in parallel: source and template line counts (excluding venv, migrations and .claude/), module count, and test count.
Step 3: Run checks
Run the project's checks to verify current health: make test, make lint,
and make check when the project has one single CI-equivalent target. If those
targets do not exist, discover the real commands from the Makefile, package.json
scripts, or CI config.
Step 4: Incremental mode check
Use the mode recorded in Step 1; an existing report alone does not select incremental mode.
For incremental audits, find what changed since the last audit date in the file
header with git log --after="<last-audit-date>" --oneline --stat | head -100,
re-analyze only those modules, and preserve findings for unchanged areas that are still
open issues. Still produce the full scorecard and executive summary.
For full audits, ignore any prior report and run Step 5 as a full analysis.
Step 5: Parallel codebase walk
If a focus area was given in the arguments provided when this skill is invoked, skip the
fan-out: analyze that area deeply in the main context, still produce all 10 scorecard
dimensions, and score non-focus dimensions from Step 2 only, marked "(surface-level)".
For full audits, call the Agent tool 3 times in a single message. Run each as a parallel helper agent. Include the Step 2
project context in each prompt. Each agent reads concrete files and runs
concrete commands (wc -l, grep, find) for evidence, and returns at most 20
findings as severity (P0-P4), title, location, issue, evidence, recommendation, plus
3-5 strengths. If an agent fails or times out, continue with the rest, mark the report
partial, and score the missing dimensions "(not analyzed)".
- Agent A, Architecture and Security: dependency graph (circular imports), data model and migrations, security architecture (auth, input validation, secrets, injection, uploads, CSP, CORS), infrastructure readiness (caching, queues, connections, rate limiting, observability), API consistency, configuration.
- Agent B, Module Quality and Patterns: service layer consistency, god files (over 500 lines), dead code, pattern consistency, type hint coverage, error handling (bare excepts, swallowed exceptions), template quality.
- Agent C, Testing, Dependencies and Operations: test quality and coverage gaps, dependency health, CI/CD quality, operational readiness (logging, monitoring, health endpoints, backups), deployment.
Step 6: Synthesize and verify
- Collect the findings from the completed agents.
- Deduplicate: merge overlaps, keeping the most detailed evidence.
- Verify with a claims ledger: for every finding, not a sample of them, re-derive
each concrete claim (a line count, path, function or variable name, query count, an
index assertion) before it enters the report.
- Order by priority first: rank findings by (severity * blast radius), reusing the agents' P0-P4 labels, and verify in that order.
- Batch per file: one targeted
grep,wc -lorReadper file answers every claim about it, not one command per claim. - Or delegate: have a verification subagent return a corrected-claims table.
- Same value: keep. Different value: correct it to the measured value.
- A claim inherently about reading code, not running it: keep it, marked "traced in code, not executed".
- A claim that cannot be re-derived (tool unavailable, timeout, file gone): drop the claim entirely, with no "unverified" hedge. A finding left with no concrete evidence is dropped too and counted in the dropped tally below.
- Budget rule: if verification cannot finish before the context runs out, drop every finding whose claims were not reached, from the report and the issue bodies, and state how many were dropped, that it was a context-budget limit, not a quality judgment, and their severities (e.g. "dropped 4 findings: 3 P3, 1 P4").
- Score the 10 dimensions from verified findings and strengths.
- Rank findings by (severity * blast radius).
Step 7: Validate labels
Only use labels and milestones that exist in the project:
gh label list --limit 1000 --json name --jq '.[].name' | sort
gh api repos/:owner/:repo/milestones --paginate --jq '.[] | "\(.number)\t\(.title)"'If a label is missing, create it with gh label create or use the closest existing one.
If the target milestone is missing, create it with
gh api repos/:owner/:repo/milestones -X POST -f title="<name>" before Phase C.
Confirm it appears in the list before passing it to --milestone.
Analysis Levels
Produce findings at four levels:
- Architecture and system design: dependency graph, data model, security architecture, infrastructure readiness, scalability (N+1 queries, missing pagination, unbounded queries, blocking calls in async paths), configuration, API consistency.
- Module health: single responsibility, interface boundaries, service layer coverage, test coverage and quality (behavior, not implementation), documentation accuracy.
- File quality: god files, dead code and orphaned assets, inconsistent patterns across similar files, configuration drift, logic in templates.
- Function and class granularity: long or multi-purpose functions, missing or wrong type hints, error handling gaps, naming inconsistencies, complex conditionals, docstring accuracy.
Evaluation Dimensions
Score each dimension 1-10 with a one-line justification: Correctness (bugs, races, data integrity), Security (OWASP Top 10, auth bypass, injection, data exposure), Performance (queries, caching, rendering, payloads), Maintainability, Testability, Extensibility (cost of a new module, feature or integration), Operability (logging, error reporting, deployment, rollback, monitoring), Documentation (onboarding path, accuracy), Code Hygiene (dead code, TODOs, style, dependency freshness), Production Readiness (what blocks a confident deploy today).
Severity Classification
- P0 (Critical): blocks a production deploy, data loss risk, security vulnerability. Fix before launch.
- P1 (High): significant maintainability or reliability risk. Fix this milestone.
- P2 (Medium): quality issue that compounds. Plan within 2 milestones.
- P3 (Low): nice-to-have or minor inconsistency. Address opportunistically.
- P4 (Note): observation. No action required.
Output Format
- Executive Summary (5-10 sentences): overall health, biggest risk, strongest aspect, readiness for a second developer and for production.
- Scorecard: the 10 dimensions with scores and one-line justifications.
- Findings by Level: grouped under Levels 1-4, each finding as:
#### [P{n}] {Short title}
**Location**: {file(s) or module(s)}
**Issue**: {What is wrong and why it matters: concrete, not generic}
**Evidence**: {Code snippet, query count, or specific example}
**Recommendation**: {Specific action to fix, not "consider improving"}- Strengths: 5-10 things done well to preserve.
- Prioritized Action Plan: top 10 findings ranked by (severity * effort-to-fix), with effort estimates.
- Onboarding Gap Analysis: for a senior developer joining tomorrow with only the repo and its docs: what is clear, what confuses, what is undocumented but critical, and what they would break on their first PR.
Phase A: Generate docs/HEALTH-AUDIT.md
Write the full audit to docs/HEALTH-AUDIT.md as a local work artifact. It must
include a tracking header, a title and date header with codebase stats (LOC, test
count, lint status), every Output Format section, a "Task Groups" section (Phase B) and
an "Action Plan" table with issue links (Phase C). Standard Markdown, no frontmatter,
no emojis.
Tracking header
Put this at the very top of the file, before the title:
<!-- audit-tracker: issues=68,69,70 folded=db-indexes:41 withheld=auth-token-storage deferred=cache-layer -->issues=lists the issue numbers created in Phase C, never a fold target.folded=lists<group-slug>:<issue number>for each group commented on an existing issue.withheld=lists slugified group names (lowercase, each run of non-alphanumeric characters collapsed to one hyphen, no commas) the user chose to hold back for disclosure. Slugify before writing, and compare carry-over names against Phase B group names case- and hyphen-insensitively.deferred=lists slugified groups deferred by the 5-issue cap or an inconclusive search.- Phase A: write
withheld=,deferred=and the open-targetfolded=entries verbatim as the carry-over set Step 1 surfaced; a closed fold target moves its group todeferred=. Omit a field with nothing to carry. - Phase C: rewrite
withheld=as the union of every group whose pre-flight choice was "withhold" and any withheld carry-over still unresolved, anddeferred=as every deferred group and any deferred carry-over still unresolved. Omit an empty field.
An abort between the two writes therefore cannot drop a carry-over name.
Withheld and deferred findings still count in every total the report states (executive summary, scorecard, action plan). State the split, e.g. "14 findings (10 filed or folded, 2 withheld, 2 deferred)".
Phase B: Group Findings into Task Batches
Group all findings into session-sized batches (2-6 hours) that touch the same files or module area and have clear dependency ordering. For each group give: name, findings (severity and title), files touched, estimated hours, dependencies, and labels from Step 7's validated taxonomy. Target 5-10 groups, never more than 10, each self-contained (a developer can pick it up cold). A group with 1 finding is too small unless it truly stands alone. Write the grouping, with a dependency diagram, into the "Task Groups" section.
Phase C: Create GitHub Issues
Disclosure pre-flight
Run this before the general confirmation below. It changes only how a security-sensitive group is published, never the scoring.
sova audit disclosureThe verdict is the last line printed: private, public-policy <path> or
public-no-policy. A failed or unrecognised visibility check is reported as public, so
the gate fails toward asking. A failed call or any other last line counts as
public-no-policy.
private(the repo is private or internal): there is no public disclosure exposure, but still resolve every carry-over group regardless of visibility. Say so, then ask once per carry-over group whether to file it now (from its Step 1 capture), drop it, or for a deferred one defer it again. Only once every carry-over group is resolved (or there were none), skip to "Choose an issue body template".public-policy <path>: read the policy and quote its private reporting instructions (advisory link, email, form) in the Withhold option of the question below, so withholding is not the only path to disclosure.public-no-policy: ask the same question without a policy quote.
Either public verdict changes the question's wording, never whether it is asked. A group needs the three-way question when it is security-sensitive (any finding came from Agent A's security architecture analysis or scored against the Security dimension, or any Issue/Evidence text names a concrete exploit path such as a specific request, payload or call sequence), plus every withheld carry-over group still unresolved. A carry-over group with no Phase B group is asked anyway, from its Step 1 capture. A deferred carry-over group that is not security-sensitive is asked only: file now, defer again, or drop. It gets no disclosure question and never triggers the report-path check.
For each such group, show its findings and ask the user to choose exactly one:
- File as-is: publish with full technical detail.
- File neutrally: publish, but drop the exploit path and evidence (keep the "what" and "why it matters").
- Withhold: file no issue this run. Record the group in
withheld=; its findings stay in the report body and in every stated total. - Drop (carry-over groups only): the group is no longer relevant or was handled
out of band. Remove it from
withheld=ordeferred=without filing, and name it in the run summary. It is not re-surfaced on a future run.
If the choice is "Withhold" or "File neutrally", check the Step 1 report path verdict
before accepting it. These choices leave the exploit detail only in
docs/HEALTH-AUDIT.md, so any unsafe-* verdict means it is one commit from public
exposure. Phase A has already written the full report to that path. Stop, have the
user resolve the path, and clean up the written copy before continuing:
unsafe-tracked:git rm --cached docs/HEALTH-AUDIT.mdand add it to.gitignore. The working copy stays on disk for Phase C.unsafe-untracked: adddocs/HEALTH-AUDIT.mdto.gitignore.unsafe-not-a-git-repo: relocate the report outside the project's distribution surface and delete the copy at the old path once the move is confirmed.
Re-ask the group's question only once the path is safe or "File as-is" was picked. Record each group's choice for "Create the issues".
With no security-sensitive or withheld carry-over group on a public repo, still ask one confirmation to file all groups normally. A public repo never skips this gate.
Choose an issue body template
Take the first that applies:
.github/ISSUE_TEMPLATE/*.md: if a template already has## Detailed Description, an## Acceptance Criteriasection with a literal- [ ], and an out-of-scope-style section (## Out of Scope,## Constraints), reuse its heading names and label.- The
issue-templateskill, if available. - The canonical structure below, the default for a portable project. It is what
compute_quality_score()scores.
## Objective
<1-2 sentence description of what this group achieves>
## Detailed Description
<Current behavior, desired behavior, and the mechanism between them, built from the
group's findings. For each finding name its file(s), the concrete issue, and why it
matters; cite severity inline, e.g. "[P1] ...".>
## Acceptance Criteria
- [ ] <Binary, testable outcome derived from the findings>
- [ ] All existing tests pass (`make check`)
- [ ] No new lint warnings (`make lint`)
## Files / Modules to Change
- [ ] `path/to/file1.py`: <what changes there>
- [ ] `path/to/file2.py`: <what changes there>
## Out of Scope / Constraints
- <Anything explicitly not covered by this group>
## Dependencies
<Links to prerequisite group issues, or "None">
## References
- Source: `docs/HEALTH-AUDIT.md` (Health Audit {date})For a "file neutrally" group, omit the exploit path or payload from "Detailed Description" and "Acceptance Criteria": describe the class of weakness and the fix.
Pre-flight checks before creating issues
- Find fold targets, posting nothing yet. For each group, search the open issues for
every file it touches (else its module or concern), quoting the path as a phrase:
gh issue list --state open --limit 1000 --search '"<path>" in:title,body' --json number,title. A failed or 1000-result search defers the group. When an open issue already covers a group's files for the same concern, the group is folded (never a withheld group): record it asfolded into #N. File at most 5 new issues per run, highest severity first. Defer any further group: keep it indeferred=for the next audit to re-ask. A carry-over group the user chose to file is exempt from the cap and from deferral: it is always folded or filed (an inconclusive search files it). - Present the proposed issues (titles, labels, milestone, and the disclosure choice for any security-sensitive group) and the folded groups with their target issue, and wait for explicit user confirmation. Nothing is published before it.
- After creation, report all issue numbers and which groups were folded, left deferred, filed neutrally or withheld.
Create the issues
For each Phase B group, plus every carry-over group the user chose to file (by either the public three-way question or the private two-way one), whose choice is not "withhold" or "drop" and that was neither folded nor deferred, create an issue from the chosen template. A carry-over group with no Phase B group is rendered from its Step 1 capture.
gh issue create --title "<type>(scope): <group description>" \
--milestone "<milestone from Step 7>" \
--label "<label1>" --label "<label2>" \
--body "$(cat <<'EOF'
<rendered template from "Choose an issue body template", for this group>
EOF
)"Only now, after the confirmation, post each folded group's findings on its target (a "file neutrally" group without the exploit path):
gh issue comment <N> --body "$(cat <<'EOF'
<the group's findings: files, concrete issue, why it matters, severity inline>
EOF
)"Then update the Action Plan table with issue numbers and links, update issues=
(created issues only), add folded=<slug>:<N> per fold, and rewrite withheld= and
deferred= per their Phase C stage. A carry-over group the user chose to file
(never deferred; a fold target counts) must gain an issue or fold and drop out of
withheld= or deferred= in the same write, never one without the other. A dropped
group gets neither. Give each withheld group's Action Plan row a withheld status and
each deferred group's a deferred status, with no issue link.
Add issues to the project board
Only issues created in this run: a fold target is someone else's issue, never added.
sova board add <issue-url> [<issue-url> ...]It prints one line per URL (added or failed (reason)) and exits non-zero when any
URL failed. A board: line names the board used (with its title when known). With no
configured board it uses the owner's only board. Act on what it prints:
skip: ...: skip board membership and say why.failedwith a missing project scope: report it. If the line says to rungh auth refresh -s project, run it, then re-runsova board addwith the failed URLs. If it names a token variable such asGH_TOKEN,gh auth refreshrefuses to run, so ask for a token with theprojectscope instead.failedwith a missing read:org scope: report it, ask for a token withread:org, and skip the board for this run.- Any other
failed: report it as "could not add to board", naming the owner and project the line names. Do not retry automatically. - A
failed:line with no URL is board-level: follow the bullet above its text matches. Any other non-zero exit with no per-URL line: report it and skip the board.
Phase D: Verify
After creating issues, verify:
- Each issue created this run (never a fold target) is on the resolved board, not merely some board. Check membership by the
board's title:
Take the title from thegh issue view <n> --json projectItems --jq '[.projectItems[].title]'board:line, else rungh project view <number> --owner "$(gh repo view --json owner --jq '.owner.login')" --format json --jq '.title'with theboard:line's number orsova config get task_source.github_project_number. Skip this check whensova board addprintedskip. An empty list, or one without that title, means not a member. A command failure is reported as "could not verify board membership", never read as "not on the board". - Labels, milestones and dependencies are correct.
- Every "withhold" group has no issue and is in
withheld=; every deferred group has none and is indeferred=. - Every "file neutrally" issue body has no exploit-path specifics.
- Every folded group's findings are commented on its target issue.
- Every carry-over group ended in exactly one of three states: filed (has an issue or
fold target, in neither field), still withheld or deferred (no issue, still in
withheld=ordeferred=), or explicitly dropped (chose "Drop"; no issue, absent fromwithheld=, named in the run summary). A group in none of them is a bug: report it rather than resolving it either way.
Constraints
- Do NOT fabricate findings. If unsure an issue exists, say what you would check.
- Do NOT pad the report with generic advice. Ground every finding in code you can see.
- Do NOT soften critical findings. DO acknowledge genuinely good patterns.
- Keep the report actionable: 30 well-prioritized findings beat a 200-finding dump.
- Maximum 10 task groups and 5 new issues per run (filed carry-over groups exempt). Before creating issues, show the grouping and ask for confirmation.
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.

