# False positives and effective reports

Two pieces of validator hygiene: knowing when a "finding" isn't a real defect, and writing reports that surface real issues without drowning them in noise.

---

## Handling False Positives

Not every flagged issue is a real problem. The validator should:

1. **Check for documented exceptions**
   - If a file contains an explicit "Exception:" or "Note:" about the flagged issue, downgrade to INFO
   - Example: `/hotfix` documents that it skips brainstorming -- this is not a missing gate

2. **Check for layered enforcement**
   - Rules setting standards + skills enforcing them is correct design, not overlap
   - Flag as INFO (acknowledged), not WARNING

3. **Check for context-specific directives**
   - "NEVER deploy without tests" (general) vs "Skip E2E tests for documentation-only PRs" (specific context)
   - The specific context exception does not contradict the general rule
   - Flag as INFO if contexts are clearly different

4. **Maintain a known-exceptions file**
   - `.claude/validation-exceptions.md` can list known acceptable findings
   - Validator checks this file before reporting
   - Each exception must explain WHY it is acceptable

5. **Check for intentional methodology-only skills**
   - Per `references/common/skill-authoring.md`, I/O Contract is OPTIONAL — pure methodology skills can omit it
   - A skill (e.g., `build-tdd`) may have no `## I/O Contract` section by design when:
     - The agent it dispatches is self-contained (carries its own protocol inline)
     - The calling command (e.g., `/feature`) owns task scope and artifact paths
     - Adding a contract would only duplicate orchestration that lives elsewhere
   - Flag as **INFO** with the note "I/O Contract intentionally omitted — pure methodology skill"
   - **Never report this as ERROR or WARNING.** A blocking severity here is a validator bug, not a skill defect.

6. **Check for asymmetric `Feeds into` declarations**
   - `Feeds into` is "Usually", not mandatory (per `skill-authoring.md`)
   - If skill A says `Feeds into: B` but B doesn't list A's artifact in `Requires`, this is **INFO**, not WARNING
   - Escalate only if you can name an actual workflow where B fails because the artifact is missing

---

## Writing Effective Validation Reports

### Do
- Reference specific files and quote the conflicting text
- Suggest concrete resolutions
- Classify severity correctly (ERROR only for true contradictions)
- Group related findings together
- Include line context so the reader can find the issue

### Do Not
- Flag every minor wording difference as a conflict
- Report style differences as errors (INFO at most)
- Flood the report with INFO items that obscure real issues
- Suggest resolutions that require rewriting entire skills
- Report the same issue multiple times from different angles