Log a proactive discovery that needs attention. Creates a factual record of WHAT was found with classification and a Findings Tracker. Use for analysis discoveries, review findings, or inspection results.
Log a proactive discovery that needs attention. Creates a factual record of WHAT was found with classification and a Findings Tracker. Use for analysis discoveries, review findings, or inspection results.
disable-model-invocation
false
argument-hint
[description]
allowed-tools
Read, Grep, Glob, Write
wrought
{"version":"1.0","tools":{"capabilities":["read_file","search_content","find_files","write_file"]},"platforms":{"claude-code":{"allowed-tools":"Read, Grep, Glob, Write","disable-model-invocation":false}},"agent":{"role":"Finding Classifier","expertise":["defect classification","risk assessment","findings tracking"],"non_goals":["fixing issues","investigation","design work"]},"execution":{"default_mode":"react","stop_conditions":["Finding report written to docs/findings/","Findings tracker created or updated","User instructed to stop"]},"output":{"format":"markdown","template":"docs/findings/{YYYY-MM-DD_HHMM}_{name}.md","required_sections":["Finding title","Classification","Evidence","Recommended next step"],"prohibited_content":["speculation","blame"]},"pipeline":{"track":"audit","standalone":true,"prerequisites":[],"produces":["docs/findings/*.md","docs/findings/*_FINDINGS_TRACKER.md"],"suggested_next":["investigate","research","design"]}}
Proactive Finding Skill
Trigger: Use /finding {description} to log a proactive discovery -- something found by analysis, review, or inspection that needs attention.
Purpose: Create a factual record of WHAT was found. Not FIX it -- that's for downstream skills.
Examples:
/finding Missing companyId filter in invoice WHERE clauses -- authorization gap
/finding Deprecated bcrypt v2.1 in auth service -- known CVE
/finding Config drift: staging environment has debug logging enabled in production
Pre-flight Check
This skill is standalone — it can be invoked at any time without prerequisites.
It is a pipeline entry point: it creates the Findings Tracker that downstream skills require.
If this invocation is part of an active workflow, check docs/findings/*_FINDINGS_TRACKER.md
for a relevant tracker and note it for context, but do not enforce stage requirements.
Instructions
Gather facts from analysis output, code inspection, or user description
Classify the finding by type and severity
Write a finding report to docs/findings/{YYYY-MM-DD_HHMM}_{name}.md
Create or update the Findings Tracker (see Findings Tracker Protocol below)
4a. Sync to GitHub Projects (NON-FATAL) — read docs/reference/github_projects_sync_protocol.md and follow Protocol A
Suggest the appropriate next step based on classification
STOP and await further instructions
Do NOT proceed with fixes, investigations, or design work -- that is the job of downstream skills.
Finding Report Rules
Factual only -- describe what you observed, not what you assume
Neutral language -- no blame, no speculation, no opinions
Specific -- exact file paths, exact code patterns, exact scope
Classified -- every finding gets a type and severity
DO: "WHERE clause in invoices.py:47 filters by user_id but not company_id"
DON'T: "Authorization is broken" or "Security is poor"
Classification Taxonomy
Finding Types
Type
Description
Resolution Branch
Defect
Known bug found proactively (not via incident)
/investigate then /rca-bugfix
Vulnerability
Security issue with known exposure
/investigate then /rca-bugfix
Debt
Technical debt requiring remediation
/design {mode}
Gap
Missing expected capability or coverage
/design {mode}
Drift
Configuration, documentation, or code divergence from intent
/design {mode} or /rca-bugfix
Severity Levels
Severity
Criteria
Critical
Active security exposure, data loss risk, or production breakage imminent
High
Significant impact on reliability, security, or core functionality
Medium
Moderate impact, workaround exists, not immediately dangerous
Low
Minor issue, cosmetic, or optimization opportunity
Write to: docs/findings/{YYYY-MM-DD_HHMM}_{name}.md
Findings Tracker Protocol
After writing the individual finding report(s), create or update a Findings Tracker. Each group of related findings gets its own named tracker. Multiple trackers can coexist in docs/findings/ — one per investigation, analysis, or problem domain.
Check docs/findings/ for existing *_FINDINGS_TRACKER.md files
If findings are clearly related to an existing tracker's scope (same system, same root analysis, same problem domain) → UPDATE that tracker by adding the new finding(s)
If findings are a new topic, or no tracker exists, or scope is unclear → CREATE a new tracker with a descriptive {findings_name}
When in doubt, create a new tracker. It is better to have two focused trackers than one bloated tracker mixing unrelated concerns.
Finding Numbering
Findings are numbered F1, F2, F3... in creation order
When updating an existing tracker, determine the next number by finding the highest existing FN and incrementing
F-numbers are stable identifiers -- never renumber existing findings
Overview Table Ordering
The overview table is always sorted by severity (most critical first): Critical → High → Medium → Low. Within the same severity level, maintain creation order. Finding detail sections in the document follow the same order as the table.
Resolution Tasks by Finding Type
Auto-generate resolution tasks based on the finding's classification:
The recommended downstream skill for each task should be included inline:
Confirm root cause → /investigate
Implement fix → /rca-bugfix
Design approach → /design tradeoff or /design migrate or /design from-scratch
If the finding report provides enough detail to make tasks more specific (exact file paths, exact code changes), replace the generic tasks with specific ones. The templates above are fallbacks.
CREATE: New Tracker Template
Write to: docs/findings/{YYYY-MM-DD_HHMM}_{findings_name}_FINDINGS_TRACKER.md
**{YYYY-MM-DD HH:MM} UTC**# {Findings Name} — Findings Tracker**Created**: {YYYY-MM-DD HH:MM} UTC
**Last Updated**: {YYYY-MM-DD HH:MM} UTC
**Origin**: {What triggered these findings, e.g., "Systems analysis of inAppDelivery extraction"}
**Session**: {Session number, if known}
**Scope**: {One-line description of what this tracker covers, e.g., "Iterable batch extraction reliability and monitoring"}
---
## Overview
{One sentence describing the scope of tracked findings.}
| # | Finding | Type | Severity | Status | Stage | Report |
|---|---------|------|----------|--------|-------|--------|
| F1 | {Brief title} | {Type} | **{Severity}** | Open | Open | [Report]({relative_path_to_finding_report}) |
**Status legend**: `Open` → `In Progress` → `Resolved` → `Verified`**Stage legend**: `Open` → `Investigating` / `Designing` → `RCA Complete` / `Blueprint Ready` → `Planned` → `Implementing` → `Reviewed` → `Resolved` → `Verified`
---
## Dependency Map
No dependencies mapped yet. Update as relationships between findings are identified.
---
## F1: {Brief Title} ({Severity} {Type})
**Summary**: {One-line factual summary from the finding report's "What Was Found"}
**Root cause**: {From the finding report's Preliminary Assessment — "Likely cause"}
**Resolution tasks**:
{Auto-generated tasks based on finding type — see Resolution Tasks section above}
**Recommended approach**: {Downstream skill from Classification Taxonomy — e.g., `/rca-bugfix` or `/design tradeoff`}
**Status**: Open
**Stage**: Open
**Resolved in session**: —
**Verified in session**: —
**Notes**: —
**GitHub Issue**: —
**Project Item ID**: —
**Lifecycle**:
| Stage | Timestamp | Session | Artifact |
|-------|-----------|---------|----------|
| Open | {YYYY-MM-DD HH:MM} UTC | {N} | [Finding Report]({relative_path_to_finding_report}) |
---
## Changelog
| Date | Session | Action |
|------|---------|--------|
| {YYYY-MM-DD HH:MM} UTC | {N} | Created tracker. F1 logged ({Severity} {Type}). |
---
## Cross-References
| Document | Description |
|----------|-------------|
| {finding_report_path} | F1 finding report |
UPDATE: Adding to an Existing Tracker
When findings are related to an existing *_FINDINGS_TRACKER.md, add them to it:
Assign next F-number: Find the highest existing FN in the tracker, use N+1
Add row to overview table: Insert in severity-sorted position (Critical first, Low last)
Add finding detail section: Insert in the same severity-sorted position (before the Changelog section, after the last finding section of equal or higher severity)
Add changelog entry: New row with date, session, and FN logged ({Severity} {Type})
Add cross-reference entry: Link to the new finding report
Update Last Updated timestamp at top of tracker
Batch Findings
When a single /finding invocation produces multiple findings (e.g., from a comprehensive analysis):
Assign F-numbers sequentially (F1, F2, F3...)
Add ALL findings to the tracker in one pass
Sort the overview table by severity after all are added
Changelog gets ONE entry: Created tracker. F1-FN logged from {source}. (for creation) or FN-FM added from {source}. (for update)
Lifecycle Tracking Protocol
Every downstream skill that processes a finding MUST update the Findings Tracker. This ensures the tracker reflects the true state of each finding at all times.
How It Works
Each finding has a Status (coarse: Open → In Progress → Resolved → Verified) and a Stage (fine-grained pipeline position)
When a downstream skill processes a finding, it updates: Stage column, lifecycle table row, resolution task checkbox, and changelog entry
The F-number (F1, F2, etc.) is the stable identifier used across all skills. Downstream skills accept F{N} as input to identify the finding
Sync to GitHub Projects (NON-FATAL) — read docs/reference/github_projects_sync_protocol.md, follow Protocol A (Finding Creation) for new findings or Protocol B (Stage Update) for existing ones. If gh fails, warn and continue.
Handoff Protocol
After writing the finding report, suggest the next step based on the finding type:
Defect or Vulnerability
Finding logged: docs/findings/{YYYY-MM-DD_HHMM}_{name}.md
Tracker updated: docs/findings/{YYYY-MM-DD_HHMM}_{findings_name}_FINDINGS_TRACKER.md (FN)
GitHub Projects: {issue_url or "sync skipped"}
Summary: {One-line factual summary}
Type: {Defect | Vulnerability} | Severity: {level}
This is a corrective fix candidate. Recommended next steps:
1. /investigate {tracker_path} (F{N}) -- to confirm scope and impact
2. /rca-bugfix {tracker_path} (F{N}) -- if cause is already clear
Awaiting your instructions.
Debt, Gap, or Drift
Finding logged: docs/findings/{YYYY-MM-DD_HHMM}_{name}.md
Tracker updated: docs/findings/{YYYY-MM-DD_HHMM}_{findings_name}_FINDINGS_TRACKER.md (FN)
GitHub Projects: {issue_url or "sync skipped"}
Summary: {One-line factual summary}
Type: {Debt | Gap | Drift} | Severity: {level}
This needs a design decision. Recommended next steps:
1. /design tradeoff F{N} {topic} -- if multiple approaches exist
2. /design migrate F{N} {topic} -- if moving between implementations
3. /design from-scratch F{N} {topic} -- if building a new capability
Awaiting your instructions.
Batch Findings (multiple from one analysis)
Findings logged:
F1: docs/findings/{YYYY-MM-DD_HHMM}_{name1}.md — {Severity} {Type}
F2: docs/findings/{YYYY-MM-DD_HHMM}_{name2}.md — {Severity} {Type}
...
Tracker: docs/findings/{YYYY-MM-DD_HHMM}_{findings_name}_FINDINGS_TRACKER.md
GitHub Projects: {issue_urls or "sync skipped"}
{For each finding, list its one-line summary and recommended next step}
Awaiting your instructions.
CRITICAL PIPELINE RULE: Suggest ONLY the next pipeline step listed in the handoff above. Do NOT offer to implement. Do NOT offer to skip pipeline steps. Do NOT offer to combine steps.
Reactive (Defect/Vulnerability): Next step is /investigate or /rca-bugfix
Proactive (Gap/Debt/Drift): Next step is /design
Do NOT continue. Do NOT add commentary suggesting any pipeline step could be skipped or is unnecessary. Wait for the user to decide how to proceed.
