borghei/Claude-Skills / engineering/code-tour
code-tour
VerifiedBuild ordered, annotated tours of an unfamiliar codebase and keep the anchors from rotting. Use when onboarding an engineer, handing off a service, or explaining a subsystem before a review.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.3 KB |
| assets/sample_tour.json | config | 5.1 KB |
| assets/tour-template.json | config | 1.3 KB |
| references/tour-construction.md | markdown | 8.5 KB |
| references/tour-maintenance.md | markdown | 8.5 KB |
| scripts/tour_propose.py | script | 9.6 KB |
| scripts/tour_render.py | script | 7.2 KB |
| scripts/tour_validate.py | script | 10.0 KB |
assets/sample_tour.json
View on GitHub{
"title": "Code Tour — how a repository becomes a tour, and how the tour stays true",
"repo": ".",
"audience": "engineer picking up maintenance of this skill",
"duration_minutes": 30,
"orientation": "Three scripts run in pipeline order: propose candidate stops, render and audit the notes, then validate the anchors against the tree. Read them in that order — each one assumes the output of the last. Nothing here touches a network or a database, so you can run every stop locally as you read it.",
"prerequisites": [
"Python 3.10+ on your path",
"Run scripts/tour_propose.py --repo scripts --max-stops 3 first, so you have seen the output the rest of the pipeline consumes"
],
"stops": [
{
"stop": 1,
"title": "Why role classification reads path components, not the path string",
"path": "scripts/tour_propose.py",
"anchor": "classify",
"line": 109,
"read_first": "The TEST_DIRS set and TEST_FILE_RE pattern above the function.",
"note": "An earlier version substring-matched hints against the whole relative path, which meant any repository with 'spec' or 'test' in a directory name had its entire source tree classified as tests and excluded from the tour. Matching against path components and a filename regex instead keeps the signal while removing the false positives, at the cost of missing unconventional test layouts — a trade worth taking, because a tour missing a stop is recoverable and a tour proposing nothing is not.",
"question": "What happens to a file at src/api/testing_utils.py? Trace both the TEST_DIRS and TEST_FILE_RE branches.",
"gotcha": "Boundary hints match on tokens split from the stem, so payment_handler.py is a boundary but paymenthandler.py is not.",
"fingerprint": "e8efad70"
},
{
"stop": 2,
"title": "Two fan-in strategies, and why the weaker one still ships",
"path": "scripts/tour_propose.py",
"anchor": "python_fan_in",
"line": 59,
"note": "Python fan-in is computed from the real AST import graph and is trustworthy. Everything else falls back to counting filename references in quotes, which over-counts common stems like index or utils. Shipping the weak heuristic rather than refusing to rank non-Python repositories is deliberate: the output is a shortlist a human curates, not a verdict, so a noisy ranking still beats alphabetical order.",
"question": "Why does the AST walk collect alias names from ImportFrom as well as the module name?",
"fingerprint": "4337d44a"
},
{
"stop": 3,
"title": "How the renderer detects a note that explains nothing",
"path": "scripts/tour_render.py",
"anchor": "audit_note",
"line": 45,
"read_first": "WHAT_ONLY_RE and WHY_MARKERS above the function.",
"note": "The audit is three cheap heuristics rather than anything semantic, because the failure it catches is blunt: notes that open by restating what the code does, notes too short to carry reasoning, and notes with no causal language at all. It will pass a well-phrased note that says nothing, and that is accepted — the goal is to catch the author who described behaviour on autopilot, not to grade prose.",
"question": "Which of the three checks would fire on the note you are reading right now?",
"gotcha": "A note can pass the audit and still be wrong. The audit checks shape, never truth.",
"fingerprint": "bdd572d5"
},
{
"stop": 4,
"title": "The whole thesis: anchors resolve by symbol, not by line",
"path": "scripts/tour_validate.py",
"anchor": "anchor_span",
"line": 46,
"note": "Tours here survive refactoring because of this resolution step. Python anchors resolve through the AST, so a stop keeps working after the file is reformatted, grows by 200 lines, or has the function moved within it — none of which a line number survives. Non-Python falls back to first-line text search, which is weaker but still immune to edits above the anchor. The recorded line is output, never identity.",
"question": "Why does the fallback branch return a 20-line window rather than a single line?",
"fingerprint": "04e718a2"
},
{
"stop": 5,
"title": "Fingerprinting",
"path": "scripts/tour_validate.py",
"anchor": "fingerprint",
"line": 77,
"note": "This function hashes the body.",
"fingerprint": "4871a7e4"
},
{
"stop": 6,
"title": "A stop that has since moved",
"path": "scripts/tour_export.py",
"anchor": "render_confluence",
"line": 12,
"note": "Included deliberately so the validator has a deleted anchor to report against this very package. Real tours accumulate these within weeks, because the code moves and the tour does not follow it unless something forces the issue — which is the entire reason validation runs in CI rather than on request."
}
],
"after": "Run the three scripts in pipeline order against this skill's own directory: propose stops from scripts/, render this tour with --audit-only, then validate it. Stop 5 fails the note audit and stop 6 fails validation, both on purpose — every finding path is exercised by the sample."
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |