get_why

The decision intelligence layer in one tool. get_why answers "why is this code shaped this way?", pulling from the architectural decision records, the wiki, and (when nothing's recorded) the git history itself. Four modes: NL search, path-anchored, target-aware, and a no-arg health dashboard.

When to call#

• Before architectural changes: check whether existing decisions govern what you're about to touch.
• During design reviews: pull the health dashboard to find stale decisions and ungoverned hotspots.
• On code with no recorded decisions: the git-archaeology fallback reconstructs the origin story from significant commits.
• Onboarding: call with no args for a tour of the codebase's recorded reasoning.

Parameters#

Returns#

The shape depends on which mode the call landed in.

Mode 1: Search (query is a question)#

• mode: "search", query
• decisions: up to 8 merged hits (keyword + semantic, deduped)
• related_documentation: top 3 wiki pages mentioning the query
• target_context: (if targets provided) per-target governing decisions, origin story, and git archaeology fallback
• code_rationale: (if targets provided and no decisions matched) rationale comments mined live from the targets' source
• episodes: dated facts recorded about the query (or the targets, when given), when any are bound

Mode 2: Path (query is a file path)#

• mode: "path", path
• decisions: governing decisions, best-first (active before proposed before deprecated/superseded), capped at 8. decisions_total appears when more than 8 matched
• origin_story: when and why the file was created, by whom, recent change patterns. The top-ranked decision also carries a still_true sentence when git evidence can speak to whether it still holds
• alignment: how well the file aligns with its governing decisions, scored over every matching record, not just the capped 8
• git_archaeology, code_rationale: fallback when no decisions govern the file. git_archaeology reconstructs from git history; code_rationale mines rationale comments live from the source and appears whenever that mining finds something, independent of what git_archaeology turned up
• episodes: dated facts recorded about this file, when any are bound. Additive, not a fallback: present alongside governing decisions too
• truncated, dropped_decisions: only if the response would have exceeded the transport budget; dropped content is recoverable via the _meta.omitted marker like any other tool

Mode 3: Health dashboard (no query)#

• mode: "health"
• summary: human-readable counts
• counts: structured counts
• stale_decisions: decisions older than the files they govern
• proposed_awaiting_review: status="proposed" records
• ungoverned_hotspots: high-churn files with no decisions
• conflicts: decisions that disagree over the same files

Mode 4: Workspace search (repo="all")#

• mode: "search", workspace: true
• decisions: merged results across repos (capped at 15)

Example#

get_why()                                     # health dashboard
get_why("why is auth using JWT?")             # search
get_why("src/auth/service.py")                # path mode
get_why("why was caching added?", targets=["src/cache/service.py"])
get_why("redis integration", repo="all")      # workspace search

Things worth knowing#

• Path detection: natural language wins first. A query ending in ?, starting with a question word ("why", "how", ...), or reading as a sentence (4+ words including a question word) always routes to search (Mode 1). Otherwise, a query containing / or \ or ending in a recognized code extension routes to path mode (Mode 2).
• Natural-language scoring weights field matches: title 3.0×, decision/rationale 2.0×, context 1.5×, the decision's own affected_files 1.5×, consequences/tags/evidence_file 1.0×. targets files contribute +5.0 for an exact match, +3.0 for a module-level match.
• Git-archaeology fallback runs when no decisions exist for a file: (1) significant commits from the file itself, (2) cross-file references in other files' commits, (3) live git log --follow and git log --grep (10-second timeout).
• Staleness score is the fraction of a decision's affected_files whose last_commit_at is later than the decision's created_at (a file named but untracked by git counts as changed too). It's the share of the decision's files that moved after the decision was recorded, not an age comparison against an "unchanged decision."
• Workspace mode (repo="all") uses keyword search across all repos' decisions, capped at 15 merged results. Full per-repo semantic federation is path-mode only.