| name | reuse-analysis |
| description | Discovers existing functions/patterns/utilities that must be reused (not reimplemented) and identifies antipatterns to avoid. Triggers at Phase 1 (discovery) and Phase 5 (verification). |
Reuse Analysis
Overview
Before building anything new, prove it doesn't already exist. This skill discovers reusable code, enforces pattern continuation, and prevents antipattern repetition.
Use this with paved-road-registry: reuse-analysis finds concrete helpers, functions, and modules not to reimplement; paved-road-registry records the broader repo-local build contract for APIs, CLIs, schemas, storage, auth, observability, tests, and runtime conventions. When a task needs an implementation_interface_contract, reuse-analysis supplies the reuse list and helps verify the interface does not reimplement an existing surface.
When to Use
- Phase 1 (discovery): Scan codebase for existing patterns before design
- Phase 5 (verification): Verify implementation didn't duplicate existing code
- Manual: When assessing whether to build or reuse
Discovery Process
Step 1: AST-Based Scan
Parse the codebase to find existing functions, classes, and utilities. Prioritize:
utils/, helpers/, common/, shared/ modules- Functions with docstrings matching task keywords
- Recently modified functions (likely well-maintained)
compound_context.learning_refs from docs/solutions/, using only compact summaries, source refs, verifier refs, and stale conditions
Step 2: Learning Store Prior Art
Read compound_context.learning_refs before broad matching. Each ref is a prior-art candidate:
- cite
path, title, summary, source_evidence, and verifier
- reject stale or unrelated refs explicitly
- never paste full solution notes into downstream prompts
- never treat a learning ref as proof of current code behavior without direct verification
Step 3: Keyword Matching
Match task description terms against:
- Function names and class names
- Docstrings and inline comments
- Module-level documentation
Step 3.5: Implementation Interface Inputs
For integration or reusable framework work, produce implementation-interface inputs:
- existing surfaces to reuse
- consumes/emits shapes visible in code, schemas, CLI payloads, workflow state, or provider contracts
- minimum fields and invariants already protected by tests or schemas
- validation gates that prove the reused surface still works
Step 4: LLM-Filtered Relevance
Rank discovered items by relevance to the current task. Filter out false positives.
Output: Reusable Items
### DO NOT REIMPLEMENT: function_name
- File: path/to/file.py:42
- Signature: def function_name(arg1: str, arg2: int) -> Result
- Purpose: One-line description of what it does
- How to use: `result = function_name("input", 42)`
Antipattern Catalog
Known bad patterns in the codebase that must NOT be repeated:
### ANTIPATTERN: descriptive_name
- What: Description of the bad pattern
- Where seen: path/to/file.py (if known, or "historical")
- Why bad: Explanation of the problem it causes
- Instead: What to do instead
Sources for Antipatterns
- Learning store (historical failures)
- Council rejection reasons (patterns that got flagged)
- Post-execution slop findings (recurring violations)
- Human edit patterns (things humans keep removing)
The concrete learning store is docs/solutions/. If it is missing or empty, record the compound_context.no_op_reasons and proceed with code and Graphify research.
Verification (Phase 5)
Reimplementation Detection
Compare new functions against the reuse catalog:
- Extract new function definitions from the diff
- Compare names and signatures against catalog
- Check for >80% code similarity with existing functions
- Flag violations with: what was reimplemented, where the original lives, how to use it
Blocking Behavior
- Near-duplicate detection (>80% similarity) BLOCKS pipeline
- Report includes specific remediation: "Use
existing_function() from path/to/module.py instead"
BPE Compliance
Remove when: Models consistently discover and reuse existing patterns without hints. At that point, keep verification (Phase 5) but remove discovery hints (Phase 1).
Common Rationalizations
| Excuse | Rebuttal |
|---|
| "My version is slightly different" | Extend the existing function. Don't duplicate and diverge. |
| "I didn't know it existed" | That's why reuse analysis runs first. Now you know. |
| "The existing code is messy" | Refactor it in a separate task. Don't create a parallel implementation. |
| "It's faster to rewrite" | Rewriting is faster today. Maintaining two versions is slower forever. |
Verification Checklist
