{"id":"codebase-recon","name":"codebase-recon","summary":"引用されたエントリーからテストまでのフローと有界クレームとしてリポジトリを再構築する。トリガーは「コードベース再調査」「このコードベースを追跡する」「リポジトリ監査」「前の再調査を更新する」です。","body":"# Codebase Recon\n\nBuild a reusable, falsifiable model of a repository. This skill reports what\nthe tree and executable probes support; it does not edit code or issue a final\nPASS/WARN/FAIL verdict.\n\n## Constraints\n\n- To prevent a floating recon, record the exact repository commit and local\n  source-of-truth precedence.\n- Because confidence is not evidence, type every material claim and cite each\n  fact and inference.\n- To preserve traceability, prefer a verified delta when a prior pack exists\n  instead of rewriting unchanged evidence as fresh discovery.\n\n## Modes, views, and lenses\n\nOne skill replaces a cluster of loose recon skills. Steer it with mode, view\nemphasis, lens, and depth — do not invent a second skill for each shape.\n\n| Control | Values | Use when |\n|---|---|---|\n| **Mode** | `baseline` \\| `delta` | First pack vs refresh after a prior recon |\n| **View emphasis** | mental model · bounded audit · pattern evidence · synthesis | Archaeology-style map, audit-style findings, pattern harvest, or executive synthesis |\n| **Lens** | persistence · auth · CLI · build · test (one per pass) | Domain-deep cut instead of a shallow whole-tree sweep |\n| **Depth** | quick · standard · deep | Orientation vs onboarding vs decision-grade evidence |\n\nAsk for the shape explicitly, for example:\n\n```text\ncodebase-recon --mode=delta --view=audit --lens=cli --depth=standard\ncodebase-recon baseline, mental-model view, persistence lens, deep\n```\n\nNatural-language equivalents count. The durable pack still carries all four\nviews; emphasis changes what you spend tokens on and what the companion report\nleads with. Pattern packaging beyond evidence pointers belongs in\n[`pattern-mining`](../pattern-mining/SKILL.md). Binding PASS/FAIL stays with\n[`validate`](../validate/SKILL.md).\n\n## Workflow\n\n1. Record the current commit and the repository's local source-of-truth\n   precedence. Search for validated prior manifests before starting with\n   `skills/codebase-recon/scripts/validate-output.sh --repo-root <target> --discover-priors`.\n   Successful empty output means no prior pack exists at either documented\n   default.\n2. If no prior pack exists, use `baseline` mode. If one exists, verify its\n   still-valid claims against the current commit and use `delta` mode. Preserve\n   valid evidence by reference and describe only changed paths and synthesis.\n3. Trace representative paths from entry point to domain logic, integration\n   boundary, and test. Prefer a few complete flows over a broad file inventory.\n4. Keep four views distinct in the report: mental model, bounded audit, pattern\n   evidence, and synthesis. Label each claim `fact`, `inference`, or `unknown`,\n   assign confidence, and cite evidence for facts and inferences.\n5. List inspected and uninspected scope. Write the JSON manifest and companion\n   report, then run the validator. Missing evidence and hidden coverage gaps are\n   contract failures, not prose caveats.\n\n## Docs-first entry-point tracing\n\nEnter through what the repository declares about itself — README, architecture\ndocs, build manifests, CLI help — and only then verify those declarations\nagainst the tree. Before the first broad search, list the declared entry points\nand trace at least one of them to code. The named failure mode is grep-first\ndrift: opening with keyword sweeps builds a model of whatever happened to\nmatch, and the recon inherits the search terms' blind spots instead of the\nrepository's actual shape. When declaration and code disagree, that is a\nfinding, not noise: record the doc's claim as `inference`, the traced behavior\nas `fact`, and cite both.\n\n## One-domain-deep lens per pass\n\nEach pass adopts exactly one lens — persistence, auth, CLI surface, build\nsystem, test harness — and follows it from entry point through domain logic to\nits tests before switching lenses. A pass ends in exactly one of two states:\nthe lens has one complete entry-to-test flow, or the report names the file and\nline where the trace was cut and why. The named failure mode is the shallow\nsweep: touching every directory at depth one produces a file inventory that\nreads like a model but supports no claim, because no path was followed far\nenough to falsify anything.\n\n## Citation floor: file:line or downgrade\n\nThe durable output doc earns its keep only if a future reader can re-verify a\nclaim without redoing the recon. Every `fact` cites file:line; every\n`inference` cites the file:line facts it rests on. A claim that cannot be\ncited is downgraded to `unknown` before the report ships — never shipped\nuncited at its original confidence. The manifest validator checks citations\nagainst the exact Git commit declared by that manifest. They must be safe\nrepository-relative regular-file paths; artifact-local and external paths are\nrejected because this schema has no digest field for those bytes. A supplied\nline number must exist in the committed blob. The validator also resolves each\nrepresentative flow path at that commit. It does not require every citation to\ncarry a line number; hold the companion report to the stricter floor: a path\nwithout a line is a pointer to homework, not a citation, and counts as a\ncoverage gap in the report's own terms.\n\nWhen reconstructing a repository other than the one that ships this skill, pass\n`--repo-root <target>` to the validator so evidence resolves against the target\ntree rather than the skill's own checkout.\n\n## Output Specification\n\n- **Artifact directory:** the caller-selected output path, defaulting to `.agents/scratch/codebase-recon/<run-id>/`\n- **Filename convention:** `codebase-recon.json` with companion report\n  `codebase-recon.md` in the same directory.\n- **Format:** `codebase-recon.v1` JSON manifest plus an evidence-cited Markdown\n  report covering the same commit, mode, flows, claims, and scope boundaries.\n  The manifest's `report` object names `codebase-recon.md` and binds its\n  lowercase SHA-256. The report carries one\n  `<!-- codebase-recon-report.v1 -->` marker plus `manifest_commit`,\n  `manifest_mode`, `flows_sha256`, `claims_sha256`, and `coverage_sha256`\n  markers computed from canonical compact sorted JSON for those sections.\n- **Validation command:** `skills/codebase-recon/scripts/validate-output.sh <codebase-recon.json>`\n  snapshots and validates both artifacts, then rechecks their identities and\n  the repository HEAD/index/worktree before returning.\n- **Downstream handoff:** pass both validated artifact paths to the requesting\n  research, planning, review, or documentation workflow; the consumer owns any\n  decision or code-change plan.\n\n### Earlier default compatibility\n\nPacks already stored under `.agents/recon/<run-id>/` remain in place. The\nvalidator's `--discover-priors` mode enumerates validated\n`codebase-recon.json` manifests under both that legacy root and the current\nscratch root. Record the selected manifest's exact path in `prior_recon`; delta\nvalidation re-validates the cited manifest and its prior chain instead of\naccepting a path merely because it exists. New packs use the current default\nunless the caller supplies a different path. Never move, copy, or delete an\nearlier pack merely to make its directory match the new state tier, because\nthat would obscure the identity a delta cites. Downstream consumers use the\nexact returned artifact paths rather than scanning only one default root. An\nearlier pack without a digest-bound companion report remains untouched but is\nnot returned as validated prior evidence under the current contract.\n\nBaseline manifests carry at least one complete entry-to-test flow. A manifest\nbeing handed off must name the target repository's current `HEAD` by its full\nobject-format OID; abbreviations and hex-looking refs are rejected. Historical\nmanifests cited as priors must likewise carry full immutable commit OIDs that\nresolve in that repository.\nDelta manifests name an existing prior recon, set `baseline_verified: true`,\nand list exactly the paths in Git's prior-commit-to-current-commit diff. The\nvalidator derives those facts rather than trusting the boolean or path list.\nIt also refuses dirty tracked, staged, or untracked source state outside\n`.agents/`, because those bytes are not bound by the declared commit. Every\nmanifest lists both inspected and uninspected scope. Manifests and companions\nmust be real regular files, are read from one snapshot, and are rechecked along\nwith HEAD and source status after validation so a mid-run swap cannot earn a\ngreen result for different bytes.\n\nThe validator is the machine boundary:\n\n```bash\nskills/codebase-recon/scripts/validate-output.sh <recon.json>\n```\n\nEvidence entries are repository-relative files at the manifest's commit,\noptionally followed by a line number.\nDelta manifests require a valid prior `codebase-recon.json` chain, an ancestor\ncommit, `baseline_verified: true`, and an exact changed-path match to the Git\ndiff ending at current `HEAD`. Enumerate validated manifests at both documented\ndefaults with:\n\n```bash\nskills/codebase-recon/scripts/validate-output.sh --repo-root <target> --discover-priors\n```\n\nExecutable behavior:\n[references/codebase-recon.feature](references/codebase-recon.feature).\n\n## Quality\n\n- Every fact and inference resolves to evidence in the manifest's exact commit;\n  unknowns remain visibly typed and never masquerade as established behavior.\n- Representative flows reach entry, domain, integration, and test surfaces,\n  while inspected and uninspected scope stay explicit.\n- The named validator passes before the JSON manifest and companion report are\n  handed to a downstream consumer.\n\n## Do not\n\n- Regenerate a full replacement report when a verified delta is possible.\n- Present an inference as fact or omit uninspected scope.\n- Turn the recon artifact into a completion verdict or a code-change plan.","author":"@boshu2","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/boshu2/agentops/tree/main/images/gemini/skills/codebase-recon","license":"Apache-2.0","category":"coding","lang":"en","tokens":2110,"stars":0,"calls30d":0,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}