By name: issue-scan description: "AI tech lead: scan codebase, discover work, propose issues (e7h4n pattern)"
Issue Scan Skill (AI-as-Tech-Lead)
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.
This skill is modeled after e7h4n's tech lead patterns.
Operations
Parse the args parameter:
- scan (default) - Full codebase scan: find bugs, tech-debt, missing features, simplification opportunities
- focus - Scan a specific module (e.g.,
focus server,focus management,focus retro) - 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)
- Bugs — Broken behavior, incorrect logic, runtime errors
- Simplification — Dead code, unnecessary abstractions, things to delete (net negative LOC is good)
- Tech Debt — Warnings, TODOs, inconsistencies, incomplete error handling
- Missing Tests — Untested entry points (API routes, CLI commands)
- Incomplete Features — Stubbed code, TODO comments, half-implemented flows
- New Features — Only if directly tied to the critical path (Run in Cloud)
Workflow
Step 1: Codebase Scan
Run these checks systematically:
# 1. Syntax errors
for f in server.js management.js process-review.js retro.js runtime-*.js; do
node --check "$f" 2>&1
done
# 2. TODO/FIXME/HACK comments
grep -rn "TODO\|FIXME\|HACK\|XXX\|STUB" *.js
# 3. Console.log leftovers (should be cleaned before commit)
grep -rn "console\.log" *.js | grep -v "// debug"
# 4. Swallowed errors (empty catch blocks)
grep -n "catch" *.js | head -20
# 5. Incomplete implementations
grep -rn "throw.*not implemented\|// TODO\|// FIXME" *.js
# 6. Test coverage gaps — API endpoints without test coverage
grep -n "url.*===\|pathname.*===" server.js
ls *test* *smoke* 2>/dev/null
Step 2: Trace Critical Path
For each finding, evaluate: Does this block the critical path?
The critical path for this project is:
Board state → Task dispatch → Agent runtime → Quality review → Evolution loop
Issues on the critical path get priority P0. Others get P1 or P2.
Step 3: Draft Issues
For each finding, draft an issue using e7h4n's 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:
## 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:
- Approve/reject each issue
- Adjust priority or scope
- Say "go" to file approved issues
Step 5: File Approved Issues
Only after user approval, create issues:
gh issue create \
--repo fagemx/karvi \
--title "<type>(<scope>): <description>" \
--body "$(cat <<'EOF'
<body content>
---
🤖 Generated by AI tech lead scan
EOF
)" \
--label "<label>"
Labels:
| Type | Label |
|---|---|
| bug | bug |
| feat | enhancement |
| refactor/chore | tech-debt |
| perf | performance |
| test | testing |
Operation: focus
Same as scan but limited to a specific module.
Workflow
- Identify the target module (e.g.,
server.js,management.js,runtime-*.js) - Read all relevant source files for that module
- Trace its exports and dependencies
- Apply the same scan categories and issue format
- 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
- List all open issues:
gh issue list --repo fagemx/karvi --state open - 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?
- Recommend: keep / close / split / reprioritize
- 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 e7h4n Would Reject)
- Epic-sized issues — "Implement S3 storage with versioning, presigning, and cleanup" → Split into 3 issues
- Vague issues — "Improve error handling" → WHERE? WHICH errors? What's the evidence?
- Implementation-prescriptive issues — "Use worker_threads for concurrency" → Describe the PROBLEM, not the solution
- Issues without evidence — Every issue must reference specific code paths or error output
- Hallucinated issues — Don't invent problems. Every finding must come from actual code scan