/why - Rationale Explanation
Understand WHY components exist, WHY certain approaches are recommended, and WHY some patterns should be avoided.
System Prompt
EXECUTION DIRECTIVE: When /why is invoked, you MUST:
- IMMEDIATELY search ADRs, standards, and documentation
- Explain first principles - connect to foundational principles
- Cite sources - reference ADRs, standards, research
- Provide alternatives considered - what was NOT chosen and why
Separation of Concerns
| Command | Responsibility | /why's Role |
|---|---|---|
/what | WHAT exists | /why: WHY it was created |
/which | WHO for task | /why: WHY this agent fits |
/how | HOW to do | /why: WHY this approach works |
/when | WHEN to use | /why: WHY timing matters |
/why | RATIONALE | Primary: design decisions |
Usage
# Why component exists
/why orchestrator # Why do we have orchestrator?
/why MoE classification # Why MoE approach?
/why self-provisioning # Why auto-install deps?
# Why approach recommended
/why use sentence-transformers # Why this library?
/why search-before-create # Why this principle?
/why separation-of-concerns # Why split responsibilities?
# Why NOT (anti-patterns)
/why not hardcode # Why avoid static data?
/why not duplicate # Why extend instead?
/why not force-push # Why dangerous?
Response Format
For /why <component>
┌─────────────────────────────────────────────────────────────┐
│ WHY: orchestrator │
├─────────────────────────────────────────────────────────────┤
│ RATIONALE │
│ ───────── │
│ The orchestrator agent exists to coordinate complex │
│ multi-agent workflows that span multiple domains. │
│ │
│ PROBLEM SOLVED │
│ ────────────── │
│ • Manual agent coordination is error-prone │
│ • Dependencies between tasks need management │
│ • Progress tracking across agents was fragmented │
│ • Failure handling required consistent approach │
│ │
│ FIRST PRINCIPLES │
│ ──────────────── │
│ • Separation of Concerns: Coordination ≠ Execution │
│ • Complete Execution: No manual steps between agents │
│ • Single Responsibility: Orchestrate, don't do the work │
│ │
│ ALTERNATIVES CONSIDERED │
│ ─────────────────────── │
│ ❌ Manual chaining: User runs agents sequentially │
│ WHY NOT: Error-prone, context lost between agents │
│ │
│ ❌ Monolith agent: One agent does everything │
│ WHY NOT: Violates separation of concerns, too complex │
│ │
│ ❌ Implicit coordination: Agents figure it out │
│ WHY NOT: Unpredictable, no progress tracking │
│ │
│ ✅ CHOSEN: Explicit orchestrator with task graph │
│ WHY: Clear control flow, trackable, recoverable │
├─────────────────────────────────────────────────────────────┤
│ SOURCES │
│ ─────── │
│ • ADR-051: Work Discovery System │
│ • CODITECT-STANDARD-AUTOMATION.md: Complete Execution │
│ • Research: Multi-agent coordination patterns │
└─────────────────────────────────────────────────────────────┘
For /why <principle>
┌─────────────────────────────────────────────────────────────┐
│ WHY: Search Before Create │
├─────────────────────────────────────────────────────────────┤
│ PRINCIPLE │
│ ───────── │
│ Always search for existing implementations before creating │
│ new ones. Extend existing components when possible. │
│ │
│ RATIONALE │
│ ───────── │
│ 1. REDUCES DUPLICATION │
│ • Duplicate code = duplicate bugs │
│ • Maintenance burden multiplied │
│ • Inconsistent behavior across similar components │
│ │
│ 2. LEVERAGES EXISTING WORK │
│ • Existing components are tested │
│ • Documentation already exists │
│ • Users already familiar │
│ │
│ 3. IMPROVES DISCOVERABILITY │
│ • Fewer components = easier to find right one │
│ • /which works better with focused inventory │
│ │
│ FIRST PRINCIPLES │
│ ──────────────── │
│ • DRY (Don't Repeat Yourself) │
│ • YAGNI (You Aren't Gonna Need It) │
│ • Occam's Razor: Simplest solution preferred │
│ │
│ IMPLEMENTATION │
│ ────────────── │
│ Before creating: │
│ 1. /what --search "capability" │
│ 2. /what agents --search "similar" │
│ 3. If found, extend existing │
│ 4. If not found, document WHY new needed, then create │
├─────────────────────────────────────────────────────────────┤
│ SOURCE │
│ ────── │
│ CODITECT-STANDARD-AUTOMATION.md: Principle #2 │
└─────────────────────────────────────────────────────────────┘
For /why not <anti-pattern>
┌─────────────────────────────────────────────────────────────┐
│ WHY NOT: Hardcoded Static Data │
├─────────────────────────────────────────────────────────────┤
│ ANTI-PATTERN │
│ ──────────── │
│ Embedding static lists, counts, or configurations that │
│ should be dynamic. │
│ │
│ WHY IT'S PROBLEMATIC │
│ ──────────────────── │
│ 1. BECOMES STALE │
│ • Data changes, hardcoded values don't │
│ • Creates inconsistency between reality and docs │
│ • Users get wrong information │
│ │
│ 2. MANUAL MAINTENANCE │
│ • Every change requires update │
│ • Easy to forget to update │
│ • Violates automation principles │
│ │
│ 3. SINGLE SOURCE OF TRUTH VIOLATION │
│ • Truth is in database/filesystem │
│ • Hardcoded is a copy, copies diverge │
│ │
│ EXAMPLE │
│ ─────── │
│ ❌ BAD: "We have 776 agents" (hardcoded in docs) │
│ ✅ GOOD: Query config/component-counts.json │
│ │
│ ❌ BAD: Static agent list in /which command │
│ ✅ GOOD: Dynamic query from component database │
│ │
│ ALTERNATIVE │
│ ─────────── │
│ Always query source of truth: │
│ • Counts: config/component-counts.json │
│ • Components: context-storage/platform.db (ADR-118 Tier 1) │
│ • Status: git status, runtime checks │
├─────────────────────────────────────────────────────────────┤
│ SOURCE │
│ ────── │
│ CODITECT-STANDARD-AUTOMATION.md: Self-Provisioning │
│ Foundational Principle #9: Based on Facts, Cross-Check │
└─────────────────────────────────────────────────────────────┘
Gap Detection
When rationale unknown:
┌─────────────────────────────────────────────────────────────┐
│ GAP DETECTED: /why <unknown-decision> │
├─────────────────────────────────────────────────────────────┤
│ No documented rationale found for this decision. │
│ │
│ SUGGESTIONS │
│ ─────────── │
│ 1. Check if ADR exists: │
│ grep -r "<topic>" internal/architecture/adrs/ │
│ │
│ 2. Check standards: │
│ grep -r "<topic>" coditect-core-standards/ │
│ │
│ 3. If undocumented, this may need: │
│ • ADR if architectural decision │
│ • Standard update if pattern decision │
│ • /how guide if implementation decision │
│ │
│ 4. To close this gap: │
│ /how create adr │
│ │
│ This gap has been logged for system evolution. │
│ File: context-storage/gap-tracking.jsonl │
└─────────────────────────────────────────────────────────────┘
Connecting to Foundational Principles
All /why answers should connect back to the 10 Foundational Principles:
- Recycle, Extend, Re-Use, Create When Necessary
- First Principles Approach
- Keep It Simple
- Separation of Concerns
- Eliminate Ambiguity
- Clear, Understandable, Explainable
- No Action Without Understanding
- No Assumptions Without Confirmation
- Based on Facts, Cross-Check
- Research When in Doubt
Related Commands
| Command | Purpose |
|---|---|
/how does <X> | How it works (mechanism) |
/when use <X> | When to use (timing) |
/what is <X> | What it is (definition) |
Success Output
When rationale explanation completes:
✅ COMMAND COMPLETE: /why
Query: <component|principle|not>
Target: <name>
Sources: N ADRs/standards cited
Alternatives: M considered
Completion Checklist
Before marking complete:
- Rationale explained
- First principles connected
- Sources cited
- Alternatives considered
Failure Indicators
This command has FAILED if:
- ❌ No rationale found
- ❌ No sources cited
- ❌ Gap not logged
- ❌ Alternatives not mentioned
When NOT to Use
Do NOT use when:
- Need location (use
/where) - Need timing (use
/when) - Need task matching (use
/which)
Anti-Patterns (Avoid)
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Skip sources | Unverified claims | Always cite ADRs/standards |
| Ignore alternatives | Incomplete understanding | Show what was NOT chosen |
| Vague rationale | No actionable insight | Connect to first principles |
Principles
This command embodies:
- #2 First Principles Approach - Explains WHY decisions were made
- #7 No Action Without Understanding - Provides rationale before implementation
Full Standard: CODITECT-STANDARD-AUTOMATION.md
Version: 1.0.0 | Created: 2026-01-03 | Author: CODITECT Team