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.