bigeasyfreeman/reuse-analysis

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

1. Learning store (historical failures)
2. Council rejection reasons (patterns that got flagged)
3. Post-execution slop findings (recurring violations)
4. 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:

1. Extract new function definitions from the diff
2. Compare names and signatures against catalog
3. Check for >80% code similarity with existing functions
4. 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

• [ ] Reuse analysis ran before design (Phase 1)
• [ ] compound_context.learning_refs checked, cited, rejected as stale, or recorded as no-op
• [ ] All reusable items listed with "DO NOT REIMPLEMENT" tags
• [ ] Implementation Interface reuse, consumes, emits, and validation gates identified when the task changes an integration boundary
• [ ] Antipatterns identified and documented
• [ ] Implementation verified: no reimplementation detected (Phase 5)
• [ ] Existing conventions followed (naming, error handling, config patterns)