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 — 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

Mode 2 — Path (query is a file path)

• mode: "path", path
• decisions — every decision affecting this file
• origin_story — when and why the file was created, by whom, recent change patterns
• alignment — how well the file aligns with its governing decisions
• git_archaeology — significant commits, cross-references, git log results (used when no decisions exist)

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

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 — if query contains / or ends with .py, the tool routes to path mode (Mode 2) instead of search (Mode 1).
• Natural-language scoring weights field matches: title 3.0×, decision/rationale 2.0×, context 1.5×, consequences/tags/files 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 compares the file's last_commit_at to the decision's last_update_at — older files with unchanged decisions are flagged stale.
• 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.