ECHO

Capture decision reasoning. Query it later. Never forget the "why."

Usage

/echo create <name> --decision "what" --reasoning "why"
/echo query <id> [question]
/echo list

What This Is

ECHO captures decision points with their full reasoning context — what was decided, why, what alternatives were rejected, and what unknowns existed at the time. When future-you asks "why did we do it this way?", ECHO has the answer.

This is architectural decision records (ADRs) made practical and queryable.

Creating an Echo

/echo create auth-strategy \
  --decision "JWT with refresh tokens over session-based auth" \
  --reasoning "Stateless scales better for our microservices architecture" \
  --alternatives "Session cookies, OAuth2 only, API keys" \
  --confidence 0.8 \
  --unknowns "Token revocation performance at scale"

Fields

Output

══════════════════════════════════════════════════════
  ECHO CAPTURED
══════════════════════════════════════════════════════
  Name:        auth-strategy
  ID:          ECHO-L6C4
  Decision:    JWT with refresh tokens over session-ba...
  Confidence:  0.8

  Query later with:
    /echo query ECHO-L6C4 'why did we choose JWT?'
══════════════════════════════════════════════════════

Querying an Echo

/echo query auth-strategy "why not session cookies?"
/echo query ECHO-L6C4 "what were the unknowns?"

Returns the full decision context including:

• The original decision
• Complete reasoning
• Rejected alternatives
• Unknowns at decision time
• Confidence level
• Date and project context

AUTO-EXECUTE Protocol

When this skill is invoked:

For /echo create <name>:

1. Parse all provided flags
2. Generate a unique ID: ECHO-XXXX
3. Save echo JSON to echoes/ directory
4. Update the echo index
5. Display the echo ID for future reference

For /echo query <id>:

1. Look up the echo by ID or name
2. Load the full decision context
3. Display the reasoning in context of the question asked
4. Log the query (useful for tracking which decisions get revisited)

For /echo list:

1. Scan the echoes directory
2. Display all captured decisions with IDs, names, and dates

Echo Data Format

{
  "id": "ECHO-L6C4",
  "name": "auth-strategy",
  "created": "2024-01-15T14:30:00",
  "decision": {
    "what": "JWT with refresh tokens",
    "reasoning": "Stateless for microservices",
    "alternatives_rejected": ["Sessions", "API keys"],
    "confidence": 0.8,
    "unknowns": ["Revocation at scale"]
  },
  "context": {
    "project": "my-api",
    "related_files": ["src/auth/middleware.ts"]
  },
  "queries": []
}

When to Use

• Choosing between architectures, libraries, or approaches
• Making tradeoff decisions you'll need to justify later
• Before and after any "should we..." discussion
• Any time the answer to "why?" matters for future work

Prerequisites

• Claude Code with Bash, Read, and Write tool access
• An echoes/ directory for storage (skill will create it if missing)
• No external dependencies — uses Python standard library only

Setup

1. Copy this folder to ~/.claude/skills/ECHO/
2. The echoes/ directory will be created automatically on first use

Decisions without reasoning are accidents. Capture the why.