Issue Scan

---
name: issue-scan
description: "Scan codebase, discover work, propose well-scoped issues"
---

# Issue Scan Skill

You are the tech lead for this project. Your job is to proactively scan the codebase, discover work that needs to be done, and propose well-scoped issues for AI agents to execute.

## Operations

Parse the `args` parameter:

- **scan** (default) - Full codebase scan: find bugs, tech-debt, missing features, simplification opportunities
- **focus <area>** - Scan a specific crate or module (e.g., `focus edda-bridge-claude`, `focus edda-mcp`)
- **review** - Review existing open issues for staleness, scope creep, or reprioritization

---

# Operation: scan

## Core Principle

**Think like a tech lead, not a developer.** You are deciding WHAT to do, not HOW to do it. Each issue you propose should be one PR's worth of work — small, focused, independently deliverable.

## Scan Categories (Priority Order)

1. **Bugs** — Broken behavior, incorrect logic, runtime errors
2. **Simplification** — Dead code, unnecessary abstractions, things to delete (net negative LOC is good)
3. **Tech Debt** — Warnings, TODOs, inconsistencies, incomplete error handling
4. **Missing Tests** — Untested entry points (API routes, CLI commands)
5. **Incomplete Features** — Stubbed code, TODO comments, half-implemented flows
6. **New Features** — Only if directly tied to the critical path (Run in Cloud)

## Workflow

### Step 1: Codebase Scan

Run these checks systematically:

```bash
# 1. Compilation warnings
cargo check 2>&1 | grep "warning"

# 2. Clippy issues
cargo clippy 2>&1 | grep "warning"

# 3. TODO/FIXME/HACK comments
grep -rn "TODO\|FIXME\|HACK\|XXX\|STUB\|unimplemented\|todo!" crates/ --include="*.rs"

# 4. Dead code markers
grep -rn "#\[allow(dead_code)\]" crates/ --include="*.rs"

# 5. Incomplete implementations
grep -rn "unimplemented!()\|todo!()\|panic!(\"not implemented" crates/ --include="*.rs"

# 6. Test coverage gaps — entry points without tests
find crates/ -name "*.rs" -path "*/src/*" | head -50
find crates/ -name "*test*" -o -name "*tests*" | head -50
```

### Step 2: Trace Critical Path

For each finding, evaluate: **Does this block the critical path?**

The critical path for this project is:
```
Transcript ingest → Event ledger → Derive views → Pack generation → Bridge injection
```

Issues on the critical path get priority `P0`. Others get `P1` or `P2`.

### Step 3: Draft Issues

For each finding, draft an issue using this format:

**Title**: Conventional commit prefix + concise description
```
bug(runner): job claim race condition when polling interval < heartbeat
feat(storage): implement S3/R2 backend for artifact persistence
refactor(sandbox): remove incomplete firecracker driver
chore(cli): remove dead code in command stubs
```

**Body structure**:
```markdown
## Background
<1-2 sentences: why this matters, what's affected>

## Evidence
<Specific file paths, line numbers, code snippets, or error output>

## What to do
1. <Step 1 — concrete, verifiable>
2. <Step 2>
3. <Step 3>

## Acceptance criteria
- [ ] <Testable condition>
- [ ] <Testable condition>

## Scope
- **In scope**: <what this issue covers>
- **Out of scope**: <what this issue does NOT cover>

## Priority
P0/P1/P2 — <one line justification>
```

**Sizing rule**: If "What to do" has more than 5 steps, split into multiple issues.

### Step 4: Present to User

Present all drafted issues as a numbered list with:
- Title
- Priority
- One-line summary
- Estimated scope (S/M/L)

**Do NOT create issues on GitHub yet.** Wait for user to:
1. Approve/reject each issue
2. Adjust priority or scope
3. Say "go" to file approved issues

### Step 5: File Approved Issues

Only after user approval, create issues:
```bash
gh issue create \
  --repo fagemx/edda \
  --title "<type>(<scope>): <description>" \
  --body "$(cat <<'EOF'
<body content>

---
🤖 Generated by edda issue-scan
EOF
)" \
  --label "<label>"
```

**Labels**:
| Type | Label |
|------|-------|
| bug | `bug` |
| feat | `enhancement` |
| refactor/chore | `tech-debt` |
| perf | `performance` |
| test | `testing` |

---

# Operation: focus <area>

Same as `scan` but limited to a specific crate or module.

## Workflow

1. Identify the target: `crates/<area>/`
2. Read all source files in that crate
3. Trace its public API and dependencies
4. Apply the same scan categories and issue format
5. Present findings to user

**Use this when**: You know which area needs attention but want a thorough review.

---

# Operation: review

Review existing open issues for quality and relevance.

## Workflow

1. List all open issues: `gh issue list --repo fagemx/edda --state open`
2. For each issue, check:
   - Is it still relevant? (code may have changed)
   - Is it properly scoped? (one PR's worth)
   - Is it on the critical path?
   - Is it blocked by anything?
3. Recommend: keep / close / split / reprioritize
4. Present recommendations to user

---

# Decision Framework

When in doubt about whether to file an issue:

| Question | If Yes | If No |
|----------|--------|-------|
| Does this block the critical path? | P0, file it | Continue evaluation |
| Is this broken behavior? | File as bug | Continue evaluation |
| Can this be deleted to simplify? | File as refactor | Continue evaluation |
| Is there a TODO/FIXME in code? | File as tech-debt | Continue evaluation |
| Is this a nice-to-have? | Skip for now | Skip |

**Default to fewer, higher-quality issues.** 5 well-scoped P0s are better than 20 scattered P2s.

---

# Anti-Patterns (Things to Avoid)

1. **Epic-sized issues** — "Implement S3 storage with versioning, presigning, and cleanup" → Split into 3 issues
2. **Vague issues** — "Improve error handling" → WHERE? WHICH errors? What's the evidence?
3. **Implementation-prescriptive issues** — "Use tokio::spawn for concurrency" → Describe the PROBLEM, not the solution
4. **Issues without evidence** — Every issue must reference specific code paths or error output
5. **Hallucinated issues** — Don't invent problems. Every finding must come from actual code scan