gc-duplicated-blocks

Skill: gc-duplicated-blocks

You are running as a garbage-collection agent for this repo. Your single job in this session is to find duplicated code blocks and file one tracker issue per finding describing them. You are not fixing anything — you are surfacing findings so a human can later schedule the work.

Trigger

Run on a manual cadence (cron-eligible, weekly is sensible) against a clean checkout. Not human-invoked at action boundaries.

Goal

Find blocks of more than 30 lines that are duplicated (verbatim or near-verbatim) across the repo, score each candidate, and open one tracker issue per real finding.

What counts as a "block"

A contiguous run of source lines (more than 30 non-blank, non-comment lines) that appears in two or more places with at least 80% line similarity. Use your judgement; this is not an AST tool. Whitespace-only differences count as identical. Renamed locals count as identical.

Where to look

All source files in the repo. Walk the working tree, focusing on hand-written code; skip the directories listed under guardrail 1.

What to skip (guardrails)

Do not open issues for duplications that fall into these buckets — they're either expected, generated, or not worth fixing:

1. Generated code or vendored deps. Anything under node_modules/, .git/, dist/, build/, .next/, target/, vendor/, **/*.d.ts, schema-migration directories (*/migrations/, */drizzle/, etc.), or files containing // AUTO-GENERATED / // DO NOT EDIT / # AUTO-GENERATED headers.
2. Schema migrations. SQL files under any migrations/ directory. Each migration is intentionally a frozen snapshot — duplication is the design.
3. Test fixtures. Files under **/__fixtures__/, **/fixtures/, **/*.fixture.*, or large expect(...) arrays in test files. Test data is supposed to be repetitive and verbose.
4. Boilerplate scaffolding. Framework-imposed shapes: shadcn/ui component shells, Next.js page/layout scaffolding (export default function Page() etc.), standard React imports, standard Express middleware wiring, Spring Boot @RestController shells, Rails ApplicationController inheritance. These are framework-imposed shapes, not duplication.
5. Type imports / re-exports. A run of import { ... } or export { ... } from '...' lines is not duplication.
6. Trivially short logic. If extracting a helper would make the code less clear (e.g., the "duplicated" block is two lines of obvious setup repeated in three test cases), skip it.
7. Tests that mirror their subject. Two tests with structurally similar arrange/act/assert blocks are normal. Only flag tests if the duplication is more than 50 lines and across unrelated files.

When in doubt: don't open the issue. False positives waste human attention and erode trust in the GC agent. It is better to surface 3 high-quality findings than 15 noisy ones.

How to score each candidate

For each candidate cluster, compute:

• Similarity (0–100): rough percentage of lines that match between instances.
• Size (lines): length of the shared block.
• Distance: are the duplicates in the same file, sibling files in one module, or across unrelated parts of the codebase? Cross-module duplication is a stronger signal that a shared helper is missing.
• Suggested action: one of:
  • extract-helper — pull into a shared function/module.
  • parameterize — same shape, differs in a few values; consolidate with parameters.
  • accept — duplication is intentional or removing it would hurt readability. (If you reach accept, you should usually just not open the issue.)

Only file an issue when size ≥ 30 lines AND similarity ≥ 80 AND the suggested action is extract-helper or parameterize.

Filing each issue

This skill is tracker-agnostic. The repo's project tracker may be GitHub Issues (gh issue create), Linear, Jira, beads (bd create), or a plain markdown report. Detect what the project uses in this priority order and use the first match:

1. .beads/ directory at the repo root → bd create.
2. gh auth status succeeds and gh repo view --json hasIssuesEnabled -q .hasIssuesEnabled returns true → gh issue create.
3. LINEAR_API_KEY env var set → Linear API.
4. JIRA_API_TOKEN env var set → Jira API.
5. None of the above → markdown-report fallback (see below).

Before filing a new issue, check for an existing GC issue covering the same duplication (search the tracker for the file paths involved — bd list --label gc / gh issue list --label gc --search "<file_a>"). If a match exists, skip — don't file duplicates on every weekly run.

The payload shape is the same regardless of tracker:

• Title: Duplicated block: <one-line summary> (one short imperative sentence; this is the issue's headline)
• Body: the structured block below

Body template:

**Locations:**
- `path/to/file_a.ts:123–187`
- `path/to/file_b.ts:42–106`

**Size:** 65 lines  |  **Similarity:** ~92%  |  **Distance:** cross-module (analysis ↔ books)

**What's duplicated:** <2–3 sentences describing the shared logic — what it does, not what it looks like>

**Suggested action:** extract-helper

**Sketch:**
<3–6 lines describing the proposed helper signature and where it would live, e.g. "Extract to `src/lib/<name>.ts` with signature `parseFoo(input: Bar): Baz`. Both call sites become a one-line call.">

**Why this matters:** <1 sentence — the cost of leaving it. e.g., "Future changes to the parsing rules need to be made in two places.">

_Filed by gc-duplicated-blocks skill._

If the tracker supports labels, add gc and duplicated-code. If not, embed them as a **Labels:** gc, duplicated-code line in the body.

If no tracker is wired up, write the findings to gc-findings/duplicated-blocks-<YYYY-MM-DD>.md at the repo root and tell the user where the report landed.

Workflow

1. Survey. Walk the working tree and list files larger than 100 lines — duplication of >30-line blocks usually lives in larger files.
2. Hunt. From the surveyed files, extract concrete seeds for grep: function/method signatures, repeated string literals longer than ~40 characters, repeated SQL/ORM call shapes. Grep each seed across the working tree; collisions are candidates. Read both sides of every candidate fully before judging — never paraphrase.
3. Filter and score. Apply the guardrails to drop generated/vendored code, fixtures, scaffolding, type re-exports, and trivial logic. Score each surviving candidate by similarity, size, and distance.
4. File issues. Aim for 3–10 findings total. If you have more after filtering, prioritise by size × similarity × cross-distance and drop the rest. File one issue per surviving finding via the project's tracker. Print the issue IDs (or report path) as you go.
5. Stop. Do not modify any source files. Do not commit anything. Do not open PRs. Your output is only the issues and a final summary printed to stdout.

Final summary

After filing, print:

=== gc-duplicated-blocks summary ===
Filed N issues:
  <id-or-path>  <title>
  ...

Skipped M candidates (reasons):
  <one-line reason per skip, grouped — e.g., "3× test fixture duplication", "2× shadcn boilerplate">

The skip list is itself useful signal — if every run skips the same category, that's a hint to update the guardrails in this skill.

Hard rules

• Read files before claiming what they contain. Never paraphrase code from memory.
• Never modify source files. This skill is read-only on the codebase.
• Restrict yourself to read-only commands (grep, ls, cat, find, git log, git diff, git show) plus the tracker's read+create commands needed for filing and dedupe. For GitHub Issues that means gh repo view, gh issue list, gh issue view, gh issue create, gh label list, gh label create --force. For beads, bd list, bd show, bd create, bd label add. No git commit, no git push, no curl, no rm, no writes to the filesystem outside the tracker call (or the fallback markdown report).
• Never open PRs, never commit, never push.
• If a tracker call fails, print the error and continue with the next finding. Do not retry blindly.