mining v0.1.2A

Immutable. This exact content is served forever at /api/v1/blob/75168d73b91abd27.

---
name: mining
version: 0.1.2
description: >
  Registry-driven mining of external example repos: the learning engine's
  second experience source. Surveys, deep-reads, and comparatively analyzes
  approved repos (vendor demos, framework samples, community robot apps) into
  evidence-cited observations (origin: external) that harden robium skills or
  propose new ones; maintains crawl records for drift re-checks. Use when:
  'mine repo X', 'survey this repo', 'run a comparative run', 'learn from
  external repos', 'distill patterns from a repo', 'crawl SOURCES.md',
  triaging or re-crawling entries in learnings/SOURCES.md. Discovery is
  autonomous; mining spends only on human-approved registry entries. Output
  is observations plus registry updates, never direct skill edits. Not for:
  absorbing robium's own session learnings (learning-loop) or fresh skill
  authoring mechanics (skill-author).
---

# Mining: learning from external examples

Working external repos encode more accumulated judgment than our own sessions
can generate. This skill turns approved example repos into evidence-cited
observations in the learnings observations tier, sharing one pipeline with
session learning (spec: docs/superpowers/specs/2026-08-01-learning-engine-design.md §6a).

## When to use this skill

- A repo in learnings/SOURCES.md is approved for exploration (status flip or
  the user says "mine repo X"; a direct naming is itself approval).
- A comparative question needs settling across sibling repos ("how do TB3 and
  TB4 sims differ on bringup?"): run a comparative set.
- A distilled repo drifted (status recheck, or a major upstream release): re-crawl.
- Candidate repos need triage into the registry (discovery: filing rows is
  autonomous; mining them is not).
- For absorbing robium's own session learnings, use the learning-loop skill.
  For authoring mechanics and the quality bar, use skill-author.

## Key directives

- Delegation posture: **embed**: the mining workflow lives here; it consumes
  the engine tools at scripts/engine/ (observations.py, verify_citations.py,
  placement.py) and the registry at learnings/SOURCES.md.
- **Spend only on approval.** <!-- id: spend-gated-registry --> Discovery
  (filing candidate rows with a one-line why) is autonomous; survey and deep
  passes run only on rows the human approved or repos the user named directly.
- **Every citation must grep.** <!-- id: citation-must-grep --> External
  observations carry source (repo@short-sha path#lines) and a verbatim quote;
  run the citation verifier before committing; a citation that fails is a
  discarded candidate, never a "close enough".
- **Observations, never skill edits.** <!-- id: observations-not-edits -->
  Mining output lands in learnings/observations/ and the registry. Skill
  content changes go through the absorb pipeline (Phase 2b) with its human
  merge gate, even for obviously-right findings.
- **Generic distills, specific doesn't.** <!-- id: generic-vs-specific -->
  Transferable patterns (idioms, orderings, workarounds, config shapes, how
  large apps are structured) become observations; project-local choices
  (names, ports, one-off tunings) are noise; drop them.
- **License gates vendoring.** <!-- id: permissive-license-only --> Check the
  repo license during survey. Pointer-first always (cite repo + path + commit);
  vendor a snippet only if short and adapted or materially modified, only from
  Apache/BSD/MIT (attribution header + upstream link + commit), never GPL into
  the plugin. Vendored files enter status unverified.
- **Code only.** <!-- id: code-only-no-history --> No issue-tracker crawling;
  commit-history mining (reverts, fix-chains) is considered-and-deferred
  (spec §6a.2); do not re-litigate it mid-run.

## Quick start

Single-repo run, end to end (repo already approved in learnings/SOURCES.md):

```bash
# 1. pin a clone (shallow is fine; the recorded SHA is the clone's HEAD)
git clone --depth 1 https://github.com/ros2/examples .robium/mining/examples
git -C .robium/mining/examples rev-parse --short=7 HEAD   # record this SHA

# 2. survey: map the tree, check LICENSE, inventory candidate areas →
#    write .robium/mining/examples-survey.md proposing which areas earn deep reads

# 3. deep pass (approved areas only): read, triage generic-vs-specific,
#    place each candidate:
python3 scripts/engine/placement.py --text "composition via NodeOptions idiom"

# 4. draft observations in learnings/observations/<skill>.md
#    (origin: external, source: repo@sha path#lines, quote: verbatim)

# 5. verify: both must PASS before commit:
python3 scripts/engine/observations.py --check learnings/observations/*.md
python3 scripts/engine/verify_citations.py --repos .robium/mining learnings/observations/*.md

# 6. update the SOURCES.md row: status → distilled, add the crawl record:
#    crawled: YYYY-MM-DD @ <sha> → fed: <obs ids>
```

Flip the row to exploring when the survey starts; survey report stays in
.robium/mining/ (gitignored) as the audit trail.

## Decision guidance

**Run type.**

| Situation | Run |
|---|---|
| One approved repo, unknown value | Survey first; deep pass only on areas the survey report proposes (or pre-authorized survey+deep in the registry row) |
| Sibling repos answering the same need (e.g. TB3 sim vs TB4 sim) | Comparative: readers fan out across all members; distill the **common/divergent split**: commons arrive pre-verified (convergence bar met by construction), divergences become decision-surface candidates for umbrella skills |
| Distilled repo with upstream drift | Re-crawl: diff against the recorded SHA, re-mine only what changed, flag distillations whose source lines changed as recheck |

Every comparative run also diffs against **our own catalog and learnings**:
where the ecosystem contradicts a skill, route it as wrong-guidance or
better-method, not as a silent overwrite.

**Evidence bar by source authority** (spec §6a.4):

| Source | Bar |
|---|---|
| Official/vendor repo, consistent with the tool's current docs | ready outright: evidence line says "official" + how docs were checked (direct fetch vs search synthesis) + date; enters the 90-day staleness sweep like any dated claim |
| Community repos, same pattern in ≥2 independent reputable ones | ready via convergence (a comparative common-split satisfies this by construction) |
| Single community repo | tentative: stays until a second witness or a robium trial |
| Extracted example files | status unverified regardless of source; promoted only by a robium trial or the deep-verify lane (Phase 3) |

**Signal mapping for mined findings:** new transferable pattern →
better-method; confirms existing skill content → verified; contradicts skill
content → wrong-guidance; domain no skill owns → no-skill-fired (route to the
new-skills observations file).

**Conflicts: record both, field-tested leads.** <!-- id: field-tested-leads -->
When mined guidance contradicts session-verified knowledge, the observation
carries both with provenance: our field-tested guidance leads, the official
idiom is noted alongside with why it bit us, and the divergence is flagged
for re-verification (upstream may have fixed the original reason).

**New-skill path** (spec §6a.6): when mining surfaces a domain no skill owns,
file a proposal in the new-skills observations file: overlap analysis (run
the placement tool over the finding set), trigger-surface sketch, evidence
inventory. The human approves the *concept* before any authoring starts;
authoring then follows skill-author. Two gates, because new skills change
catalog shape.

## Platform gotchas

- Shallow clones (`--depth 1`) satisfy citation verification for the HEAD
  commit only. For a re-crawl diff, fetch the recorded SHA first:
  `git -C <clone> fetch --depth 1 origin <sha>`.
- Big repos (navigation2, IsaacLab): use a blobless clone to survey cheaply:
  `git clone --filter=blob:none <url>`; blobs download lazily on read.
- Prefer git clones over the GitHub API for reading (no rate-limit surprises;
  the clone is also what the citation verifier needs).
- Licenses live in LICENSE/LICENSE.md at the repo root but subdirectories can
  carry their own (vendored third-party dirs); check the directory you are
  actually citing from.

## Customization

- Comparison sets are defined in the registry: list the member repos in one
  row's Notes (or a dedicated subsection) and mine them in a single run.
- User tier (Phase 4 preview): the same flow with a private registry at
  .robium/sources.md, observations in the user's repo, and overlay skills as
  the absorb destination; mined-from-private content gets an extra provenance
  review before any upstream contribution.

## References

- Registry: learnings/SOURCES.md (statuses, crawl records, discovery inbox).
- Observations contract: the README in learnings/observations/ (schema, ready
  bar, external-entry fields).
- Engine tools (repo root): scripts/engine/observations.py (lint),
  scripts/engine/verify_citations.py (citation check),
  scripts/engine/placement.py (target/overlap report).
- Pattern-recognition heuristics: the skill-author skill's mining-guide
  reference (what makes a pattern worth distilling); still the judgment core.
- Spec: docs/superpowers/specs/2026-08-01-learning-engine-design.md §6a.

## Changelog

- 0.1.2 (2026-08-03): style pass; removed em dashes throughout (no content changes).
- 0.1.1 (2026-08-02): pointers updated: learning-loop landed; hardening
  references retargeted.
- 0.1.0 (2026-08-02): initial skill: registry-driven survey→deep and
  comparative runs, extraction contract, source-authority evidence bar,
  conflict policy, new-skill proposal path (learning-engine Phase 2a, spec §6a).