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

•
Read .claude/specs/index.json from the project root
- •If the file does not exist, report "No existing specs found. Clean slate -- no overlaps possible." and exit early
•Read .claude/tasks/index.json 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
•Exclude: completed, cancelled

If all specs are completed or cancelled, 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 .claude/tasks/index.json exists, also check for overlap at the task level:

•
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
•
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

code

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

code

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

code

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

No existing specs found (.claude/specs/index.json 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: Report no active overlap, list closed specs for reference
•Empty requirement text: Ask the user to provide more detail (minimum 20 characters needed for meaningful analysis)
•Very broad requirement: If the requirement is too broad (matches >3 specs at partial-overlap level), suggest narrowing the scope before creating a spec
•Requirement matches a cancelled spec: Note it -- "A similar spec (SPEC-004) was previously cancelled. Reason may be relevant to this new effort."