# Auto Mine Repo > Mine an ai-sdlc team document out of a repository that already describes its own process, unattended. Nobody is interviewed. - Skill: `nikiforovall/auto-mine-repo` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add nikiforovall/auto-mine-repo` - Raw SKILL.md: https://api.skillmd.com/api/skills/nikiforovall/auto-mine-repo/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: NikiforovAll (https://skillmd.com/u/nikiforovall) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nikiforovall/auto-mine-repo --- # auto-mine-repo Some repositories already describe a delivery process. An agentic bundle names its skills, its agents, its gates and the artifacts they pass; a toolkit's README argues for its own order of work. That is a document waiting to be projected, and reading it is faster and more accurate than asking a team to recall it. You are reading files, not people. Everything that follows exists to keep that distinction visible on the page — because a mined document that reads like an interviewed one is a document a team will trust further than it should. The run is **unattended**: inventory, read, author, verify and report without checking in. It stops in exactly one place — the three decisions below, none of which the source can settle — and it resumes the moment they are answered. Anything else that feels like a question is a call you make from the evidence and name in the report. ## What you are producing A **draft**. `status: draft` in `team.yaml`, and the document's `description` says in its first line that it was read out of a repository and nobody was interviewed. The output is not the end of the work. It is the thing a coach reads *at* a team so they can cut it — which is the `mapping-session` skill's job, starting from a folder that already exists. A mined document that is never taken to a team describes a package; only the team can turn it into a description of a team. ## Before the first file 1. **Know what you are reading and where it goes.** The source package and the destination folder are the arguments — `/ai-sdlc:auto-mine-repo --into ` — and either one that is missing is a question, not a guess. 2. **Write the folder outside this repo** — beside the source, or wherever that team's material already lives. This repository is vendor-neutral by invariant: no client, product, or employer vocabulary belongs in it, and neither do documents mined from someone else's licensed package. The folder name becomes the team id. 3. **Run `ai-sdlc new `** for a renderable skeleton, then replace its contents. It writes the team as several files read as one document; the cheatsheet's *Layer 1* section says which. 4. **Read the `sdlc-ontology` skill**, and its `references/ontology-cheatsheet.md` — the model on one page. The authored-versus-derived distinction is the one that matters: if you find yourself wanting to draw an arrow, name an artifact instead. 5. **Read `references/inference-rules.md`** in this skill. It is the mapping from repository evidence to model element, and it is the reference you consult all the way through. ## Take the inventory before you author anything Enumerate the whole surface of the package into a scratch file, then author against that list and strike entries off as they land: ```bash find -maxdepth 4 -type f \( -path '*/skills/*' -o -path '*/agents/*' \ -o -path '*/commands/*' -o -path '*/hooks/*' -o -path '*/workflows/*' \) | sort cat /README.md /CHANGELOG.md 2>/dev/null ls /*plugin*/*.json 2>/dev/null ``` Keep the paths, not the file names alone: a package with both `skills/` and `agents/` gives one undifferentiated list otherwise, and `.claude/skills//SKILL.md` is the layout most of these packages use. The failure this prevents is the one that happens by default: you read the README, the README describes the main flow beautifully, you author the main flow, and you never notice the four standalone skills the README mentions once in a table. **Coverage comes from a list you check off, not from attention.** Anything you decide to leave out is something you name in the hand-off report, not something you quietly drop. Read in this order, because later sources correct earlier ones: | Source | What it settles | | --- | --- | | README / architecture reference | the spine, the vocabulary, the arguments | | Gate or contract references | who resolves what, and on what evidence | | Artifact / lifecycle references | what is produced and consumed, by name | | Plugin manifest | which hooks exist, and at which points | | `SKILL.md` / agent front matter | one-line purpose, hard constraints, whether it is standalone | | CHANGELOG | why something is the way it is, and what it replaced | ## Surface the decisions before authoring This is the one stop in the run. Three calls change the finished picture more than anything else, and **none of them is derivable from the source**. Put all three to the user in one message, with your recommendation, before you write a process file — then finish the document without stopping again: **1. How many documents.** One package is one document; a program of several repositories is a judgement. The evidence for *one* is a shared lifecycle — the same task conventions, the same commit rules, one tracker — and cross-references between the repos. The evidence for *several* is separate audiences: a document each team can be handed without reading the other two. Ask before authoring, not after. The routes are: **one document, repositories appear as harnesses and tools** — or **one folder per repository, and the shared lifecycle is authored as many times as there are folders**. Getting this wrong is the only decision here that cannot be fixed by editing; it is re-mining. **2. How the processes are cut.** | Cut | You get | You pay | | --- | --- | --- | | **By mode** — one process per entry point | the contrast is on the page: the same activity, a different resolver and a different level | the spine is authored twice, and every later edit lands in two files | | **By domain** — one delivery process, modes as sibling sub-activities | nothing is authored twice | the contrast moves inside a drawer, where a reader has to go looking for it | **3. How fine the artifacts are.** One artifact per file the package names (a review diff, the lens findings, the fix-up diff, the check verdict — sixty or more), or one per thing that visibly changes hands (one review verdict — thirty or so). Fine granularity makes the flow figure honest about the machinery; coarse granularity makes it readable. State each choice in the document's `description` once it is made. A reader who can see the cut can argue with it. ## The loop Catalogs first — one file per shelf — then one process at a time. Within a process: read the source for that flow end to end, then write it, then run `ai-sdlc status ` and fix what it names before starting the next. Carry the `refs:` as you go, never afterwards. Every shelf entry takes one, and on a mined document it is not decoration: the whole claim to accuracy is that a reader can open the file each entry was read from. Write it while the file is still on your screen — a `refs:` pass at the end is a pass where you guess. Write the spine before the tooling. A stage, a role, an artifact and an activity are cheap to get right and expensive to retrofit; a fill is a two-line edit. Two YAML traps cost a round-trip every time, and both come from quoting a package that writes in Markdown. A plain scalar may not **start with a backtick**, and may not **contain a colon followed by a space** — `note: \`make test\` is the gate` and `description: reviewed against master: architecture, tests` both fail to parse. Wrap the value in double quotes, or make it a block scalar — and for a markdown `description:` the block must be literal `|-`, never folded `>-`, which joins consecutive lines and silently collapses a table or a list into one paragraph. Mining hits this far more often than an interview does, because so much of what you are quoting is prose about file names and commands. ## Four things only the source can say Everything else in the model is evidence. These four are the places where a mined document goes wrong in a way no reader can detect: - **`open:` — only from a declared gap.** A roadmap item, a documented limitation, a "not yet implemented", a TODO with a sentence attached. Quote it as the `need:`. If the package has not asked for something, the document must not ask on its behalf: the gap between blueprint and fill is the most honest signal this product produces, and inventing one destroys it. - **`why:` — only from the source's own argument.** Quote or compress the rationale the package gives. A `why:` that restates the activity's name is worse than no `why:`, and one you wrote yourself is a claim about a team you never met. No argument in the source, no `why:` on the page. - **Roles — always marked as inferred.** A package names gates, owners and stand-ins; it does not name people. Write the roles the documents imply, and say in each role's `description` — or at minimum in the team `description` — that these are inferred and need confirmation. - **Levels — from the mechanism, not the tone.** See the ladder table in `references/inference-rules.md`. A README that sounds confident is not evidence of autonomy; a hook at a fixed point is. | Rationalization | Reality | | --- | --- | | "The activity is bare, the page looks unfinished" | A bare activity is work the team does itself. It is the most common state in a real document. | | "The docs are clearly aspirational, so I'll model what they meant" | Model what they wrote. Where writing and reality differ, that is the team's finding to make, not yours. | Order is derived from artifacts, so a package's loops need modelling rather than drawing — `references/inference-rules.md` says how. ## Finishing Three checks, in order, and all three must pass before you report: ```bash ai-sdlc check # schema; must exit 0 ai-sdlc status # no dangling ids, nothing unreferenced ai-sdlc export --out .html # the build prints the page count: processes + 2 ``` `status` is the one that catches mining mistakes specifically. A dangling id renders silently — the cheatsheet's *Verifying* section says which kinds fail loudly — and an unreferenced catalog entry is the other direction: a tool you inventoried and never placed, which means either an activity is missing or the entry is not part of this document. `--out` names the one-file export, which is the thing you hand over. **Write the document's own honest-about paragraph last**, from what `status` actually printed. Written before the processes are authored, it becomes a prediction, and a mined document that opens by miscounting its own open slots has undermined the only thing it was claiming: that every number in it came from somewhere. The same applies to each process's "where it is open" note. Then report, in this order: 1. The counts `status` prints — activities, filled, open, unclaimed. 2. **The three decisions** you put to the user, and that only the first is expensive to reverse. 3. **What you left out**, from the inventory list, and why. 4. That the roles are inferred and the `why:` lines are quoted, so the team knows which parts are evidence and which are reading. 5. That the next step is `mapping-session` against this folder, with the team in the room.