Code Walk

/code-walk — query-time impact walk (DOC-164 slice 9)

The first query-time skill in the agentic-code-ontology layer. Where slices 5-8 BUILT the ontology, slice 9 USES it: the maintainer types a free-form question about a proposed feature or change, the feature-advisor subagent reads the full ontology + live docs, and emits a structured impact assessment.

A walk answers: what concepts does this touch, what implicit / explicit ADRs constrain the design, what refactoring scopes overlap, what doc gaps does it open or close, what test gaps does it open or close, and what's the rough implementation skeleton anchored on existing patterns.

The walk is a planning aid, not an implementation. The maintainer reads it, applies judgment, decides what to do next (implement / scope down / draft an ADR / log a refactoring sprint).

Argument forms

Prerequisites

• lineage/{repo}/understanding/{slug}.md sidecars exist (i.e. /enrich has been run).
• lineage/{repo}/concepts.yaml exists (i.e. /concepts has been run).
• lineage/{repo}/implicit-adrs.md exists (i.e. /find-implicit-adrs has been run).
• lineage/{repo}/refactoring-scopes.md exists (i.e. /find-implicit-adrs slice-8-fix has been run).
• lineage/{repo}/doc-gaps.md exists (i.e. /doc-gap-check has been run) — recommended.
• lineage/{repo}/test-map.yaml exists (i.e. /test-coverage has been run) — recommended.
• adrs/ directory exists (drafts + accepted ADRs).

If a recommended artefact is missing, the walk still proceeds but flags the absence in ontology_coverage_gaps.

Protocol

1. Orient

Read these (skip if loaded this session):

• CLAUDE.md — quality bar
• adrs/drafts/agentic-code-ontology.md — slice 9 in slice progression
• .claude/agents/feature-advisor.md — the subagent's system prompt

2. Capture the question

If the maintainer passed the question as the first argument, use it verbatim.

If no argument was passed, use AskUserQuestion:

1. "What feature or change do you want to walk? Free-form. The agent reads the full ontology and produces a structured impact assessment. Examples: 'I want to add per-data-entity alert recipient routing' or 'I'm thinking about adding rate-limiting to the GenAI proxy — what's affected?'"

3. Resolve inputs

Derive these (the skill does this; the agent receives them as inputs):

• REPO: from --repo flag or default odd-platform.
• WORKSPACE_ROOT_ABS: pwd.
• REPO_ROOT_ABS: <workspace>/../{repo} (the target repo).
• SIDECAR_DIR_ABS: <workspace>/lineage/{repo}/understanding/. Confirm at least one sidecar exists; otherwise abort with "no sidecars — run /enrich first."
• CONCEPTS_YAML_PATH: <workspace>/lineage/{repo}/concepts.yaml. Confirm exists; otherwise abort with "no concepts — run /concepts first."
• IMPLICIT_ADRS_PATH: <workspace>/lineage/{repo}/implicit-adrs.md. Confirm exists.
• REFACTORING_SCOPES_PATH: <workspace>/lineage/{repo}/refactoring-scopes.md. Confirm exists.
• DOC_GAPS_PATH: <workspace>/lineage/{repo}/doc-gaps.md. If missing, pass empty + flag.
• TEST_MAP_PATH: <workspace>/lineage/{repo}/test-map.yaml. If missing, pass empty + flag.
• EXISTING_ADRS_DIR_ABS: <workspace>/adrs/.
• SUBSTRATE_LAST_SCAN_COMMIT: parse <workspace>/lineage/{repo}/manifest.yaml's last_scan_commit.
• SLUG: derive from the question. Pick 3-6 salient words; kebab-case; max ~50 chars (e.g. per-data-entity-alert-routing, genai-proxy-rate-limiting, attachment-storage-validation). Avoid stop words.
• TARGET_PATH: lineage/{repo}/feature-walks/{date}-{slug}.md. Use Bash(date +%Y-%m-%d) for the date prefix.

If the feature-walks/ directory doesn't exist, the agent's Write will create it (Write tool creates parent dirs).

4. Spawn the feature-advisor subagent

Invoke via Agent tool with subagent_type: feature-advisor. Construct the prompt:

REPO: <repo>
WORKSPACE_ROOT_ABS: <absolute>
REPO_ROOT_ABS: <absolute>
SIDECAR_DIR_ABS: <absolute>
CONCEPTS_YAML_PATH: <absolute>
IMPLICIT_ADRS_PATH: <absolute>
REFACTORING_SCOPES_PATH: <absolute>
DOC_GAPS_PATH: <absolute>
TEST_MAP_PATH: <absolute>
EXISTING_ADRS_DIR_ABS: <absolute>
SUBSTRATE_LAST_SCAN_COMMIT: <commit>
TARGET_PATH: lineage/{repo}/feature-walks/{date}-{slug}.md
SLUG: <slug>
QUESTION: |
  <verbatim>

Tools per the agent's frontmatter: Read, Glob, Grep, WebFetch, Write. The agent reads the ontology, fetches live docs (≤5 fetches), writes one file, replies with Wrote: <path> + Confidence: ....

5. Validate

After the agent completes:

• Confirm lineage/{repo}/feature-walks/{date}-{slug}.md exists.
• Parse the YAML frontmatter; verify artefact: feature-walk, prompt_version, slug, confidence_overall, ontology_inputs_consulted.
• Verify the body has all named sections (Question, Restated as concepts, Affected nodes, Related concepts, ADRs to respect, Refactoring scopes touched, Doc gaps to address, Test gaps to cover, Suggested implementation skeleton, Ontology coverage gaps, Open questions for the maintainer, sources, confidence_per_section, Maintainer notes).
• Spot-check 2-3 cited sources: pick a random affected_nodes.[i] ← {slug}.md:LINE and confirm the sidecar exists; pick a random adrs_to_respect.[i] ← <path>:LINE and confirm the ADR exists.
• Verify no banned phrases ("probably", "likely", "should", "looks right", "presumably", "defensible") in the body. If found, flag the maintainer.
• Verify Open questions for the maintainer (if populated) doesn't punt research-answerable questions. Spot-check: if a question is "what auth mode does X use?" — that's research-punting; flag.

6. Report

• Path to the new walk.
• One-line confidence summary from the agent's exit.
• Counts: <N> affected nodes, <C> concepts, <A> ADRs, <S> scopes, <D> doc gaps, <T> test gaps, <G> ontology coverage gaps, <O> maintainer-only open questions, <U> doc URLs fetched.
• Top finding: the single most-load-bearing item the maintainer should consider (typically the highest-severity DEVIATES ADR or the highest-severity overlapping refactoring scope).
• Suggested next: read the walk; decide whether to (a) implement now, (b) scope down, (c) draft an ADR alongside, (d) sequence behind a refactoring scope, (e) commission more enrichment for ontology gaps the walk surfaced.

--show form

Read the existing walk at lineage/{repo}/feature-walks/{slug-or-date}.md. If <slug-or-date> is a partial match, list candidates and pick the most recent. Print the body.

--list form

Glob lineage/{repo}/feature-walks/*.md. For each, parse the frontmatter and print <date> | <slug> | <first line of maintainer_question>. Sort by date descending.

Rules

• Live URLs only for docs. The agent enforces this internally (Rule 1). The skill verifies the agent's output's sources block doesn't claim doc content from anything other than WebFetch-cited URLs.
• Maintainer is the decision-maker. The walk is advisory. Don't auto-trigger /implement, don't auto-create backlog items, don't auto-draft ADRs. Surface findings; let the maintainer choose.
• Don't pre-summarise the walk. The walk's value is in its citations and structure. Reporting "TL;DR: this is fine, ship it" defeats the artefact. The skill reports counts and the top finding; the maintainer reads the walk for substance.
• Walks accumulate as planning history. Don't overwrite existing walks at the same slug — if a walk already exists for today's date + slug, append a numeric suffix (-2, -3).

Cross-references

• Subagent: .claude/agents/feature-advisor.md
• Inputs: lineage/{repo}/understanding/*.md + lineage/{repo}/concepts.yaml + lineage/{repo}/{implicit-adrs,refactoring-scopes,doc-gaps,test-map}.{md,yaml} + adrs/**/*.md + live ODD docs
• Output: lineage/{repo}/feature-walks/{date}-{slug}.md
• ADR: adrs/drafts/agentic-code-ontology.md rev 2 (slice 9 in slice progression)
• Memory: ~/.claude/projects/.../memory/feedback_research_dont_punt.md (the rule against punting research as "open questions")