mock-code-finder

Imported from vrazdalovschi/dotfiles (agents/skills/shared/mock-code-finder/SKILL.md). Install upstream with npx skills add vrazdalovschi/dotfiles --skill mock-code-finder. Copyright stays with the author.

Mock Code Finder

Core Insight: Long-running multi-agent projects accumulate stubs, mocks, placeholders, and TODO code that silently degrades the codebase. Systematic multi-method detection finds what grep alone misses.

The Problem

Unless you've specifically looked for them, chances are that you've accumulated various forms of "mocks" or fake placeholder code somewhere in your project. Single-keyword grep misses structural stubs (short functions that do nothing substantive). AST analysis alone misses TODO comments. You need both, plus heuristics.

THE EXACT PROMPTS

Phase 1: Discovery

First read ALL of the AGENTS.md file and README.md file super carefully and understand ALL of both! Then use your code investigation agent mode to fully understand the code and technical architecture and purpose of the project.

Then, I need you to search every last INCH of this ENTIRE repo, looking intelligently for ANY signs or indicators that functions, methods, classes, etc. are "stubs" or "mocks" or "placeholders" or "TODO" or otherwise rather than 100% real, working, fully-functioning code.

You can apply a variety of methods for checking for this, but it's imperative that you not miss ANY instances of this sort of thing. One clever way might be to use ast-grep to find and measure the length of any functions/methods/classes/etc. in terms of lines, characters, etc. to look for things that look suspicious because they appear to be too short to do anything substantive.

First compile the comprehensive listing of all such placeholders/mocks/stubs and a short explanation or justification for why you're convinced they qualify as incomplete/placeholders that must be completed. Once we have this table of suspects, we can then decide how to address and resolve them all in a totally comprehensive, optimal, clever way.

Phase 2a: Resolution (Short List — ~4 items or fewer)

OK good, now I need you to come up with an absolutely comprehensive, detailed, and granular plan for addressing each and every single one of those placeholders/mocks/stubs that you identified in the most optimal and clever and sophisticated way possible. THEN: please resolve ALL of those actionable items now. Keep a super detailed, granular, and complete TODO list of all items so you don't lose track of anything and remember to complete all the tasks and sub-tasks you identified or which you think of during the course of your work on these items!

Phase 2b: Resolution (Long List — 5+ items, project uses beads)

OK good, now I need you to come up with an absolutely comprehensive, detailed, and granular plan for addressing each and every single one of those placeholders/mocks/stubs that you identified in the most optimal and clever and sophisticated way possible.

THEN: please take ALL of that and elaborate on it and use it to create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid, with detailed comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the over-arching goals of the project.) The beads should be so detailed that we never need to consult back to the original markdown plan document. Remember to ONLY use the `br` tool to create and modify the beads and add the dependencies.

Phase 3: Bead Refinement (iterate 2-3 times)

Check over each bead super carefully-- are you sure it makes sense? Is it optimal? Could we change anything to make the system work better for users? If so, revise the beads. It's a lot easier and faster to operate in "plan space" before we start implementing these things! DO NOT OVERSIMPLIFY THINGS! DO NOT LOSE ANY FEATURES OR FUNCTIONALITY! Also make sure that as part of the beads we include comprehensive unit tests and e2e test scripts with great, detailed logging so we can be sure that everything is working perfectly after implementation. Make sure to ONLY use the `br` cli tool for all changes, and you can and should also use the `bv` tool to help diagnose potential problems with the beads.

Quick Start

Step 0: Detect Project Tooling

# Check for beads
if [ -d ".beads" ] && command -v br &>/dev/null; then
  echo "BEADS_AVAILABLE=true"  # Use Phase 2b workflow
else
  echo "BEADS_AVAILABLE=false" # Use Phase 2a workflow
fi

Step 1: Understand the Project

cat AGENTS.md README.md   # DOCUMENTATION FIRST — always!

Then use Explore agent for full architecture understanding.

Step 2: Multi-Method Scan

Run all detection methods in parallel (see DETECTION-METHODS.md):

# Text-based detection (ripgrep)
rg -n "TODO|FIXME|HACK|XXX|STUB|PLACEHOLDER|MOCK|DUMMY|FAKE|TEMP|TEMPORARY" \
  --type-not json --type-not lock -g '!target/' -g '!node_modules/' -g '!.git/' .

rg -n "unimplemented!|todo!|panic!\(\"not implemented|NotImplementedError|raise NotImplementedError" .

rg -n "pass$|return None$|return \{\}$|return \[\]$|return \"\"$|return 0$" \
  --type py --type rust --type ts --type js .

# Structural detection (ast-grep) — find suspiciously short functions
ast-grep run -l Rust -p 'fn $NAME($$$) { $SINGLE_STMT }' --json 2>/dev/null
ast-grep run -l Rust -p 'fn $NAME($$$) -> $RET { todo!() }' --json 2>/dev/null
ast-grep run -l Python -p 'def $NAME($$$):
    pass' --json 2>/dev/null
ast-grep run -l TypeScript -p 'function $NAME($$$) { return; }' --json 2>/dev/null

Step 2.5: Behavioral Detection (Learned From Real Sessions)

Beyond keywords and AST, look for simulated behavior patterns:

# Fake work: sleep() used to simulate real operations
rg -n "sleep\(|thread::sleep|time\.sleep|setTimeout.*simul|fake.*delay" \
  --type rust --type py --type ts --type go .

# Hardcoded scores/metrics (should be computed from data)
rg -n "score\s*=\s*[0-9]|rarity.*=\s*[0-9]|count.*=\s*0[^.]" \
  --type rust --type py --type ts .

# Returns 501 Not Implemented (API route stubs)
rg -n "501|Not Implemented|not.yet.implemented" \
  --type ts --type py --type rust .

# Functions that always return the same thing regardless of input
# (trace callers to confirm — if callers depend on real output, it's a stub)
rg -n "fn.*->.*bool.*\{.*true.*\}|fn.*->.*bool.*\{.*false.*\}" --type rust .

Step 2.6: Cross-Reference and Caller Tracing (Critical!)

For each suspect, trace callers to understand impact:

# Find who calls a suspect function
rg -n "function_name\(" --type rust --type ts --type py .

# Check if the stub's callers depend on real output
# Example: batch-enrichment.ts returned `redFlagsDetected: 0` but the
# API route that called it actually counted them — divergent code paths

Step 3: Compile Findings Table

Add a "Real Blocker?" column to triage what's fixable now vs blocked:

| # | File:Line | Type | Code Snippet | Why It's Suspicious | Real Blocker? |
|---|-----------|------|-------------|---------------------|---------------|
| 1 | src/foo.rs:42 | stub | `fn process() { todo!() }` | Explicit todo! macro | No — just needs implementation |
| 2 | src/bar.rs:100 | placeholder | `fn validate() -> bool { true }` | Always returns true | No — needs real validation logic |
| 3 | lib/baz.py:55 | mock | `def fetch_data(): return {}` | Returns empty dict | Yes — needs API credentials |
| 4 | src/metrics.rs:100 | hardcoded | `dau_count = 0` | Always 0, no real tracking | Yes — needs analytics pipeline |

Categorize each finding as one of:

• Just needs code — No external dependency, can implement now
• Blocked on infra — Needs DB schema, API keys, external service (document the blocker)
• Dead code — No callers, stub is unreachable (candidate for deletion)
• Intentional stub — Abstract base / trait impl / protocol method (false positive, skip)

Step 3.5: Check Existing Beads (Avoid Duplicate Work)

If the project uses beads, check what's already tracked:

br list --status=open 2>/dev/null | grep -i "stub\|mock\|placeholder\|todo\|implement"

Only create new beads for findings not already tracked.

Step 4: Resolve (Branch by Tooling)

• Beads available + 5+ items → Phase 2b: Create beads with br, refine with bv
• No beads or <5 items → Phase 2a: Plan and resolve with TODO tracking

Detection Methods Summary

Full detection patterns by language: DETECTION-METHODS.md

Beads Workflow (When Available)

When the project has .beads/ and br CLI:

1. Create parent epic: br create --title="Resolve all mocks/stubs/placeholders" --type=epic --priority=1
2. Create child tasks: One bead per stub/mock, with detailed comments including:
   • What the stub currently does
   • What it should do (the real implementation)
   • Which files need changing
   • What tests to add
   • Dependencies on other stubs (if resolving one requires another)
3. Add dependencies: br dep add <child> <depends-on> for implementation ordering
4. Refine with bv: bv --robot-triage to validate dependency graph, find quick wins
5. Iterate in plan space: Review and refine beads 2-3 times before implementing
6. Include test beads: Every stub resolution bead should have a companion test bead

Lessons From Real Sessions

Patterns discovered across 7+ repos (midas-edge, frankensearch, mcp-agent-mail-rust, rch, ntm, flywheel-connectors, jeffreysprompts):

Full detection patterns with these behavioral checks: DETECTION-METHODS.md

Anti-Patterns

Checklist

• Understand project: Read AGENTS.md, README.md, explore architecture
• Detect tooling: Check for .beads/ and br CLI
• Keyword scan: ripgrep for TODO/FIXME/STUB/MOCK/PLACEHOLDER/etc.
• Unimplemented scan: todo!(), unimplemented!(), NotImplementedError, pass
• Return value scan: Hardcoded returns, empty returns, always-true/false
• AST scan: ast-grep for suspiciously short functions/methods/classes
• Behavioral scan: sleep() as fake work, hardcoded scores, 501 routes, disabled features
• Caller tracing: For each suspect, trace callers to confirm real dependency on output
• Divergent path check: Look for same concept implemented differently in two places
• Stub test check: Test files with <5 assertions may themselves be stubs
• Compile table: All suspects with file:line, type, snippet, justification, blocker status
• Categorize: Just-needs-code / Blocked-on-infra / Dead-code / Intentional-stub
• Check existing beads: Avoid creating duplicates of already-tracked issues
• Choose workflow: Beads (5+ items) or TODO list (<5 items)
• Plan resolution: Comprehensive, detailed plan for each item
• Refine plan: 2-3 iterations in plan space before implementing
• Resolve all items: Implement real code, add tests
• Verify: Run tests, re-scan to confirm zero remaining stubs

References