| name | find-dupes |
| description | Find potential duplicate Shortcut stories, present pairs for review, execute decisions (archive, merge, link) |
| disable-model-invocation | true |
Find Dupes
Find potential duplicate stories in Shortcut, present pairs for review, and
execute decisions: archive the loser, merge content, add story links.
This is primarily a hygiene play, not a recurring one. Play 1 (/sync-ideas)
catches duplicates at intake via semantic matching against the existing backlog.
This skill is for periodic sweeps or after bulk imports that bypassed Play 1.
Also Read
Before starting, read these shared sections from box/shortcut-ops.md:
- Search Operators: Shortcut search syntax
- Workspace Constants: Shortcut IDs, workflow states
- General Constraints: mutation cap, rate limiting
Constraints
- Mutation gate: A PreToolUse hook blocks all Shortcut mutations through
Bash. Route through
agenterminal.execute_approved or present the command
for the user to run.
- Human-in-the-loop: Present one pair at a time with full content for
comparison. Wait for Paul's decision. Don't batch-execute without review.
- Before Shortcut API calls: check
reference/tooling-logistics.md for
tested recipes. Story link creation uses /api/v3/story-links, NOT a
nested endpoint under stories.
Steps
1. Load candidates
Pull active stories by state. Don't manually curl Shortcut for the card list:
python3 box/shortcut-cards.py --query '!is:archived !state:Released state:"In Definition"' --summary
Repeat for other active states (Need Requirements, Backlog, Build,
Test). Exclude archived and Released stories from analysis.
2. Identify duplicate pairs
Lead with semantic judgment. Read titles and descriptions. Use your
judgment to identify pairs that describe the same need from different angles.
The first run (2026-02-11) showed this catches nuances that keyword similarity
misses — e.g., SC-28 and SC-140 being the same feature from different angles.
Keyword/Jaccard similarity (>=35% shared terms) can pre-filter large candidate
sets but isn't the primary detection method.
3. Present and decide
Present one pair at a time with full content for comparison. Possible decisions:
- Keep one (archive the other)
- Combine into one (merge content)
- Keep both (distinct enough)
- Keep both + "relates to" link (related but not duplicates)
4. Execute decisions
For each approved decision, use the wrapper scripts via execute_approved.
Scripts include idempotency checks and read-back verification. Exit 0/1/2.
- Archive:
python3 box/shortcut-mutate.py archive STORY_ID. Carry over
the archived story's Slack permalink to the surviving story (preserves
provenance).
- Story links:
python3 box/shortcut-mutate.py story-link SUBJECT_ID OBJECT_ID "duplicates".
Use verb duplicates (loser to winner) or relates to.
- Product Area: May need reassignment during resolution. The surviving
card should reflect the real product area, not just the surface where the
idea was filed.
- Content merge: When combining, merge the loser's content into the
winner under a
## Merged from SC-{id} heading.
Idempotency
Before each mutation, check:
- Story link already exists before creating
archived status before archiving## Merged from SC-{id} heading already present before merging content
