Assess Findings

Assess Findings

Recommended model tier: balanced (sonnet) - this skill requires reading code and making judgement calls

Triage static analysis findings by reading the actual code, assessing whether each finding is genuine or noise, and accepting (dismissing) irrelevant ones using findings_accept. Accepted findings are hidden from future output by default.

Prerequisites

• Findings must already exist. If findings_stats returns zero counts, tell the user to run:

  ./.aide/bin/aide findings run --path .
  

• The findings_accept tool must be available (provided by the aide MCP server).

Available Tools

Read-only (shared with patterns skill)

Decisions (conformance context)

Write (unique to this skill)

Code inspection

Workflow

0. Load the Decisions

Call decision_list first — it is authoritative, where the "Project Decisions" block in session context is a session-start snapshot that can predate a decision changed since. Fall back to the block only if the tool is unavailable. Decisions are the recorded architectural commitments for this project; a finding that evidences a decision violation is not noise, whatever its analyzer or severity says.

Keep the list to hand for step 3. You are not searching the codebase for violations here — that is the review skill's job. You are checking whether findings the analyzers already produced happen to be evidence of one.

1. Get the Landscape

Call findings_stats to understand the scope:

findings_stats
-> Returns: counts per analyzer (complexity, coupling, secrets, clones) and severity

If the user asked to focus on a specific analyzer or severity, note that and filter accordingly. Otherwise, work through all findings systematically.

2. Prioritise Review Order

Work through findings in this order:

1. Secrets (critical first) — these need immediate attention; false positives are common in test fixtures
2. Complexity (critical, then warning) — assess whether high complexity is inherent or decomposable
3. Clones (all) — determine if duplication is extractable or structural boilerplate
4. Coupling (all) — assess whether high fan-in/fan-out is expected for the file's role

3. Assess Each Finding

For each finding or group of related findings:

1. Read the finding details — note the file, line range, and metric values
2. Read the actual code — use code_outline first, then Read with offset/limit on the flagged section
3. Check it against the decisions from step 0 — see "Decision conformance gate" below
4. Make a judgement call using these criteria:

Decision conformance gate

Before applying any accept criterion, ask: does this finding evidence a violation of a recorded decision?

A finding is decision-linked when the code it flags contradicts a decision's stated commitment. For example:

• a deadcode finding on a symbol written ahead of its integration, against a decision requiring all code to be reachable from real call paths
• a secrets finding in a runtime path, against a decision on credential handling
• a coupling finding crossing a boundary a decision declared off-limits
• a security finding using a mechanism a decision ruled out

Reachability findings turn on intent, not on whether a caller was found. A deadcode finding is decision-linked when the symbol is genuinely unused — written ahead of its integration, or left behind after it. It is not decision-linked when the symbol is reached by a mechanism the analyzer cannot see: framework convention (file-based routing, dependency injection, reflection), a declared entry point, generated code, or a test fixture. Those are analyzer blind spots, and accepting them is the correct resolution — name the mechanism that reaches the symbol as the rationale.

no-aspirational-code bans code waiting for a caller that does not exist. It does not ban code whose caller aide cannot index. Reading every unreferenced symbol as a violation would make a framework page component permanently unacceptable, and a finding with no legal resolution is one that trains people to ignore the whole gate.

A decision-linked finding cannot be accepted as noise. There are exactly two valid resolutions:

1. Fix the code so it conforms — the finding disappears on the next findings run.
2. Amend the decision — if the decision is genuinely wrong or has been superseded, say so explicitly and tell the user to run /decide on that topic. Do not accept the finding on the assumption that the decision will change.

If you are unsure whether a finding is decision-linked, name the mechanism you believe resolves it — the route that reaches the symbol, the reason the string is not a credential — and keep the finding if you cannot name one. "Unsure" is not falsifiable and defaulting to linked turns the gate into a ratchet; a named mechanism can be checked and argued with. Report anything kept this way under "Decision conflicts" so a human decides.

Note the limits of this gate. It grades findings the analyzers already produced; it cannot find a decision violation that no analyzer flagged. For a code-level sweep against the decisions, use the review skill.

Accept (dismiss) when:

• Complexity: The function is inherently complex (CLI dispatch, protocol handling, state machines) and cannot be meaningfully decomposed without harming readability
• Clones: The duplication is structural boilerplate (e.g., CLI subcommand wiring, store method patterns) where extraction would require framework-level abstraction
• Coupling: High fan-in/fan-out is expected for the file's architectural role (e.g., a main entry point, a facade, a registry)
• Secrets: The flagged string is a test fixture, example config, documentation placeholder, or env var name (not an actual secret)

Keep (do NOT accept) when:

• The finding points to a genuine problem that should be fixed
• Complexity can be reduced by extracting helper functions
• Duplication can be resolved by creating a shared utility
• A coupling cycle exists that indicates poor module boundaries
• A string looks like it could be a real secret or credential
• The finding is decision-linked (see the conformance gate above) — this overrides every accept criterion

4. Accept Findings

Use findings_accept to dismiss noise. You can accept:

• By IDs — for individual findings after assessment:

  findings_accept ids=["finding-id-1", "finding-id-2"]
  

• By filter — for bulk dismissal of an entire category:

  findings_accept analyzer="clones" file="cmd/"
  

Always explain why each finding is being accepted before calling the tool.

5. Report Summary

After completing the triage, produce a summary:

## Findings Triage Summary

### Before

- Total: X findings (Y critical, Z warnings, W info)

### Accepted (Dismissed)

- N findings accepted as noise/irrelevant
  - Complexity: X (inherent complexity in [files])
  - Clones: Y (structural boilerplate in [area])
  - Coupling: Z (expected for [role])
  - Secrets: W (test fixtures / placeholders)

### Decision Conflicts (must not be accepted)

- K findings evidence a violation of a recorded decision
  - `<decision-topic>` — file:line — [what the code does vs what the decision requires]
  - (omit this section entirely when there are none)

### Remaining (Genuine)

- M findings require attention
  - [List each with file:line and brief description]

### Recommendations

1. [Prioritised action items for genuine findings]

Decision Criteria Reference

Failure Handling

1. No findings — Tell user to run ./.aide/bin/aide findings run --path . first
2. findings_accept not available — The aide MCP server may not expose this tool; tell the user to update aide
3. Uncertain about a finding — When in doubt, keep it. It's better to flag a false positive for human review than to dismiss a real issue
4. Large number of findings — Work in batches by analyzer. Accept obvious noise first, then do detailed code review for borderline cases
5. decision_list returns nothing — The project has no recorded decisions; skip the conformance gate and say so in the summary. Do not invent decisions

Verification

• Called decision_list (or noted the fallback) before triaging
• Called findings_stats for baseline counts
• Reviewed each finding category (secrets, complexity, clones, coupling)
• Read actual code for every finding before accepting
• Checked every finding against the recorded decisions before accepting it
• No decision-linked finding was accepted
• Provided rationale for each acceptance
• Produced summary with before/after counts
• Remaining findings are genuinely actionable