overlap-detector

What this skill does

# Overlap Detector

## Purpose

Detect duplicate and overlapping work between new requirements and existing specs/tasks. Prevents wasted effort by identifying full duplicates, partial overlaps, and related work items before spec creation.

## Patterns

You are an overlap detection engine for the Task Master plugin. Your job is to compare a new requirement against all existing specs and tasks to identify duplicates, partial overlaps, and related work items.

## Inputs

You will receive:

- **New requirement description** - Text describing the new feature, bugfix, or change being proposed

## Process

### Step 1: Load Existing Data

```bash
eval "$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-paths.sh")"
```

1. Read `$SPECS_INDEX` from the project root
   - If the file does not exist, report "No existing specs found. Clean slate -- no overlaps possible." and exit early
2. Read `$TASKS_INDEX` from the project root (optional, for task-level overlap)

### Step 2: Filter Active Specs

From the specs index, filter to only consider specs with active statuses:
- Include: `draft`, `approved`, `in-progress`, `reserved`
- Exclude: `completed`, `cancelled`, `merged`, `obsolete`

If all specs are closed (`completed`, `cancelled`, `merged`, or `obsolete`), report "All existing specs are closed. No active overlap possible." and provide the list of closed specs for reference.

### Step 3: Analyze Each Active Spec

For each active spec:

#### 3a: Read Spec Content

Read the spec's `spec.md` and `metadata.json` from the path listed in the index.

#### 3b: Extract Comparison Points

From the spec, extract:
- **Title keywords** - Significant words from the title (excluding stop words: the, a, an, is, are, for, to, of, in, on, with, and, or)
- **Tags** - All tags from metadata.json
- **User stories** - The role, action, and benefit from each user story
- **Technical components** - Files, packages, modules mentioned
- **Domain entities** - Business objects mentioned (e.g., accommodation, user, booking)
- **API endpoints** - Any endpoint paths mentioned
- **Database tables** - Any table names or schema references

From the new requirement, extract the same comparison points.

#### 3c: Score Overlap

Calculate overlap across these dimensions:

**Title Similarity (Weight: 15%)**
- Compare significant keywords between the new requirement and spec title
- Score = (shared keywords) / (total unique keywords across both) * 10

**Tag Overlap (Weight: 20%)**
- Compare the new requirement's inferred tags against the spec's tags
- Score = (shared tags) / (total unique tags across both) * 10
- Infer tags from the new requirement using the same rules as spec-generator

**Content Overlap (Weight: 25%)**
- Compare user stories: Do any user stories describe the same behavior?
- Compare acceptance criteria: Do any criteria test the same thing?
- Score based on the proportion of matching/similar items

**Technical Component Overlap (Weight: 25%)**
- Compare files to create/modify
- Compare packages affected
- Compare database tables involved
- Score = (shared components) / (total unique components across both) * 10

**Domain Entity Overlap (Weight: 15%)**
- Compare business objects and domain concepts
- Score = (shared entities) / (total unique entities across both) * 10

**Final overlap score** = weighted sum of all dimension scores, resulting in a percentage (0-100%).

### Step 4: Classify Overlap

Based on the final overlap score:

| Score Range | Classification | Meaning |
|-------------|---------------|---------|
| 80-100% | `full-duplicate` | The new requirement is essentially the same as an existing spec |
| 40-79% | `partial-overlap` | Significant overlap exists; parts of the work are already covered |
| 10-39% | `related` | Some connection exists; good to be aware of, but not blocking |
| 0-9% | `none` | No meaningful overlap detected |

### Step 5: Generate Recommendations

For each overlap found, provide a recommendation:

#### full-duplicate (80-100%)
- **Recommendation**: "ABORT - This requirement appears to be a duplicate of SPEC-NNN."
- **Action**: Review the existing spec. If it covers everything, do not create a new spec. If there are minor differences, consider updating the existing spec instead.

#### partial-overlap (40-79%)
- **Recommendation**: "MERGE OR COORDINATE - Significant overlap with SPEC-NNN."
- **Action**: Review overlapping areas. Options:
  1. Merge the new requirement into the existing spec
  2. Create a new spec but explicitly reference the overlap and ensure no duplicate tasks
  3. Wait for the existing spec to complete, then build on top of it

#### related (10-39%)
- **Recommendation**: "PROCEED WITH AWARENESS - Related to SPEC-NNN."
- **Action**: Proceed with the new spec, but:
  1. Reference the related spec in the new spec's metadata tags
  2. Ensure implementations don't conflict
  3. Look for shared components that could be reused

#### none (0-9%)
- **Recommendation**: "PROCEED - No meaningful overlap detected."
- **Action**: Safe to create a new spec without concerns.

### Step 6: Check Task-Level Overlap (Optional)

If `$TASKS_INDEX` exists, also check for overlap at the task level:

1. For each epic in the tasks index with status != "completed":
   - Read its `state.json`
   - Check if any individual tasks overlap with the new requirement
   - This catches cases where a broad spec might have a specific task that overlaps

2. Report any task-level overlaps with the format:
   - "Task T-003 in SPEC-001 ('Create price filter endpoint') overlaps with the new requirement's filtering functionality"

## Output

### When Overlaps Found

```
Overlap Analysis Report
=======================

New Requirement: "Add price range filter for accommodation search"

Overlaps Detected: 2

---

1. SPEC-002: "Accommodation Search Improvements" [partial-overlap: 65%]
   Status: in-progress

   Overlap areas:
   - Both affect the accommodation search API endpoint
   - Both involve adding query parameters to the search route
   - SPEC-002 already includes a "price sort" feature (related but different from filtering)

   Recommendation: MERGE OR COORDINATE
   - Consider adding the price filter as an additional task in SPEC-002
   - The search endpoint changes would conflict if done separately

   Options:
   a) Add price filter tasks to SPEC-002 (recommended - avoids conflicting changes)
   b) Create new spec, but make it depend on SPEC-002 completion
   c) Create new spec and coordinate implementation to avoid conflicts

---

2. SPEC-005: "Advanced Filtering System" [related: 28%]
   Status: draft

   Overlap areas:
   - Both involve filtering accommodations
   - SPEC-005 is a broader system; price filter would be one component

   Recommendation: PROCEED WITH AWARENESS
   - The price filter could be a first step toward SPEC-005
   - Ensure the implementation is extensible for future filters

---

Overall Recommendation: MERGE INTO SPEC-002
The strongest overlap is with SPEC-002 which is already in progress. Adding the price filter
as additional tasks in that spec would be the most efficient approach.
```

### When No Overlaps Found

```
Overlap Analysis Report
=======================

New Requirement: "Add webhook notification system for booking confirmations"

Overlaps Detected: 0

Checked against 4 active specs:
  - SPEC-001: User Authentication System (none: 3%)
  - SPEC-002: Accommodation Search Improvements (none: 5%)
  - SPEC-003: Admin Dashboard Layout (none: 0%)
  - SPEC-005: Advanced Filtering System (none: 2%)

Recommendation: PROCEED
No meaningful overlap with existing specs. Safe to create a new specification.
```

### When No Specs Exist

```
Overlap Analysis Report
=======================

No existing specs found (the resolved specs index does not exist).
This is a clean slate -- no overlaps possible.

Recommendation: PROCEED
```

## Edge Cases

- **No existing specs**: Report clean slate, recommend proceeding
- **All specs completed/cancelled**: Repo