Skills

Mine Best Practices

Extract insights from PR review threads, validate against codebase, and consolidate into the best practices library.

Your Role as Orchestrator

You are the orchestrator for this multi-stage pipeline. Your responsibilities:

1. Execute scripts - Run the Python scripts that prepare batches and aggregate results
2. Launch subagents - Create Task() calls to dispatch specialized subagents for extraction, validation, and synthesis. Max 10 concurrent — if more batches exist, wait for a wave to complete before launching the next.
3. Validate outputs - After each phase, review subagent outputs for quality, format correctness, and issues
4. Stop on anomalies - If you detect problems (malformed output, unexpected results, low yield), stop and alert the user. Do not attempt to fix issues on-the-fly.

Key principle: Validate each stage's output before proceeding. Only interrupt the user when something needs human judgment.

When to Use This Skill

Use when:

• Building/updating the best practices library from recent PRs
• Mining a date range of PR reviews for patterns
• Seeding the library from historical review threads

Don't use for:

• Reviewing code against the library of current practices
• General PR reviews

Usage

/mine-best-practices --since 2025-01-01
/mine-best-practices --since 2025-06-01 --until 2025-07-01 --scope backend

All date ranges refer to PR merge date (inclusive on both ends).

Advanced

For debugging and manual intervention:

/mine-best-practices resume validate --identifier web_2025-01-29
/mine-best-practices status
/mine-best-practices pending
/mine-best-practices for-topic error_handling

--batch-size and --id-prefix are tuning parameters rarely needed in normal operation.

Data Refresh

Before mining, ensure threads are up to date:

python3 scripts/mine.py refresh                          # Incremental (new PRs only)
python3 scripts/mine.py refresh --since 2025-01-01       # From specific merge date
python3 scripts/mine.py refresh --since 2026-01-09 --until 2026-01-26  # Specific range
python3 scripts/mine.py refresh --full                   # Full re-extraction

Requires gh CLI authenticated with repo access. Safe to re-fetch overlapping ranges (deduplicates by thread_id).

Execution Workflow

NOTE: All commands run from the skill directory (where this SKILL.md lives).

Step 1: Start Extraction

python3 scripts/mine.py extract --since 2025-01-01 --scope backend

Outputs extraction Task prompts for each batch.

Step 2: Launch Extraction Subagents

Launch the Task prompts from Step 1 in parallel using the Task tool.

Output: tmp/mining_{identifier}/extraction/batch_{n}.yaml

After subagents complete, validate:

• Check each batch output file exists
• Verify YAML format is correct (insights list, skipped entries)
• Review yield rate (typically 30-40% extracted, 60-70% skipped)
• Spot-check 2-3 insight content samples for quality
• Stop and alert user if: yield is unusually low/high, format errors, or quality issues

Step 3: Aggregate Extraction

python3 scripts/aggregate_extraction.py {identifier}

Merges results into insights.yaml and outputs validation Task prompts.

After aggregation, validate:

• Verify insights.yaml was updated with new insights
• Check insight count matches expected (extracted - duplicates)
• Review a few insight content samples
• Stop and alert user if: counts don't match, format issues, or quality concerns

Step 4: Launch Validation Subagents

Launch validation Task prompts in parallel using the Task tool.

Output: tmp/mining_{identifier}/validation/batch_{n}.yaml

After subagents complete, validate:

• Check each batch output file exists
• Verify YAML format is correct (rejections list)
• Review rejection rate (expect 0-10% for recent threads, higher for older)
• Spot-check rejection reasons for appropriateness
• Stop and alert user if: rejection rate is surprisingly high/low, unclear rejection reasons, or format issues

Step 5: Aggregate Validation

python3 scripts/aggregate_validation.py {identifier}

Updates insights.yaml with validation results and outputs topic assignment prompt.

After aggregation, validate:

• Verify insights.yaml statuses updated (pending → validated or rejected)
• Check all pending insights were processed
• Review rejection reasons if any
• Stop and alert user if: missing updates, unexpected rejection patterns

Step 6: Launch Topic Assignment

Launch the topic assignment Task prompt(s) in parallel.

Output: tmp/mining_{identifier}/topics/batch_{n}.yaml

After subagents complete:

1. Read all topics/batch_{n}.yaml outputs
2. Merge all assignments lists into one topics.yaml in the working directory
3. Deduplicate __new__: topics: same name across batches → keep as-is (natural merge). Similar but differently-named proposals → flag to user for resolution.
4. Verify all insight_ids were assigned, check topic distribution is reasonable
5. Stop and alert user if: many new topics proposed, odd distribution, or missing assignments

Step 7: Dispatch Synthesis

python3 scripts/dispatch_synthesis.py {identifier}

Applies topic assignments and outputs synthesis Task prompts (one per topic).

After dispatch, validate:

• Verify insights.yaml was updated with topic assignments
• Check all validated insights have topics
• Review new topic files were created (for __new__: topics)
• Stop and alert user if: assignments missing, too many new topics, or odd groupings

Step 8: Launch Synthesis Subagents

Launch synthesis Task prompts in parallel using the Task tool (one per topic).

Output: Updates library/{topic}.yaml directly.

After subagents complete, validate:

• Check each topic's library file was updated
• Verify YAML format is correct
• Review subagent summaries (preserved/updated/added counts)
• Spot-check 1-2 updated practices for quality
• Stop and alert user if: files weren't updated, format errors, or suspicious changes

Step 9: Verify Synthesis Quality

Check that:

• Existing practices were preserved appropriately
• New practices are well-written and actionable
• One-off patterns were filtered (not everything became a practice)
• Code examples are correct and follow codebase conventions

Stop and alert user if: practices were deleted without replacement, excessive additions, or empty library files.

Step 10: Aggregate Synthesis

python3 scripts/aggregate_synthesis.py {identifier}

Marks all validated insights with topics as synthesized.

Step 11: Build

python3 scripts/build_sections.py

Generates markdown files for the review skill.

Output: the configured sections_output_dir

Step 12: Verify

python3 scripts/mine.py status
python3 scripts/mine.py pending

Confirm:

• status shows insights as synthesized
• pending shows no remaining work

Step 13: Build Review Rules

python3 scripts/build_bugbot.py

Produces Task prompts for generating bugbot rules from the library. Launch the Task prompts (one per scope). Each subagent reads the existing BUGBOT.md and library practices, then merges incrementally — adding rules for new practices, removing rules for deleted practices, and preserving unchanged rules verbatim.

Sections use ## {topic} headings (matching library filenames) with **{practice_title}** rule keys. Related practices are synthesized into fewer condensed rules.

Targets: Scope-specific rules files from config.yaml

After subagents complete, verify:

• Diff is minimal — only new/removed/updated rules, not full rewrites
• New rules are mechanical and actionable (not vague design guidance)
• No duplication with root .cursor/BUGBOT.md (manually maintained cross-cutting rules)

Status Commands

python3 scripts/mine.py status        # Overview: threads, insights, library
python3 scripts/mine.py pending       # What needs work at each stage
python3 scripts/mine.py for-topic X   # All insights for topic X

Data Locations

• Threads: code_insights/threads.yaml
• Insights: code_insights/insights.yaml
• Library: code_insights/library/*.yaml
• Working dir: tmp/mining_{identifier}/

Architecture

User: /mine-best-practices --since 2024-01-01
  |
  v
mine.py --> Batch threads, output extraction prompts
  |
  v
Extraction subagents (parallel) --> batch_n.yaml
  |
  v
aggregate_extraction.py --> insights.yaml + validation prompts
  |
  v
Validation subagents (parallel) --> batch_n.yaml
  |
  v
aggregate_validation.py --> insights.yaml + topic prompt
  |
  v
Topic assignment subagent --> topics.yaml
  |
  v
dispatch_synthesis.py --> synthesis prompts (per topic)
  |
  v
Synthesis subagents (parallel) --> library/{topic}.yaml
  |
  v
[VERIFY: Check for anomalies]
  |
  v
aggregate_synthesis.py --> insights.yaml (status: synthesized)
  |
  v
build_sections.py --> sections/*.md
  |
  v
build_bugbot.py --> bugbot rules (via subagent)

Notes

• Extraction filters out already-processed thread_ids
• Validation checks patterns against current codebase
• Synthesis prioritizes recurring patterns over one-offs
• Library practices derive from insights.yaml (full provenance)