gh-explain

Explain: What Did AI Build?

Context loader for interactive Q&A about what AI built on your behalf. Loads the decision journal, diff, issue context, and source files so you can ask questions grounded in evidence.

Tool Usage: This command uses the AskUserQuestion tool for session save decisions.

Contract

GOAL: Load all available context about an issue/PR and present a comprehension brief, then enable conversational Q&A. Testable: user can ask questions and get answers grounded in actual code, decisions, and issue context.

CONSTRAINTS:

• Never fabricate decisions or rationale not present in the journal or diff
• Always distinguish between journal-recorded decisions and inferred decisions
• If context is incomplete, state what's missing rather than guessing

FORMAT: Comprehension brief displayed first, then open-ended conversation.

FAILURE CONDITIONS (output is unacceptable if any apply):

• Claims about decisions that aren't in the journal or diff
• Answers not grounded in loaded context
• Context loading fails silently (must report what's missing)

Phase 1: Context Loading

Step 1.1: Determine Target

If $ARGUMENTS is provided, normalize it to a numeric issue/PR number:

ISSUE_NUM=$(echo "$ARGUMENTS" | grep -oE '[0-9]+$')

If $ARGUMENTS is not provided, detect from current branch:

BRANCH=$(git branch --show-current)
ISSUE_NUM=$(echo "$BRANCH" | grep -oE 'issue-[0-9]+' | grep -oE '[0-9]+')

If no issue number found from branch or arguments, ask via AskUserQuestion tool:

• "Which issue or PR would you like to explore?"

Step 1.2: Load Context (Parallel)

First, read journal directory and explain config from settings:

# Read explain config from settings (local > project > user > default)
GHW_CONFIG=$(jq -n '
  def defaults: {
    journal: { dir:".decisions" },
    explain: { sessionSave:"ask", includeDiff:true }
  };
  defaults
    * (try input catch {})
    * (try input catch {})
    * (try input catch {})
' "$HOME/.claude/settings.gh-workflow.json" \
  ".claude/settings.gh-workflow.json" \
  ".claude/settings.gh-workflow.local.json" 2>/dev/null)

JOURNAL_DIR=$(echo "$GHW_CONFIG" | jq -r '.journal.dir')
INCLUDE_DIFF=$(echo "$GHW_CONFIG" | jq -r '.explain.includeDiff')
SESSION_SAVE=$(echo "$GHW_CONFIG" | jq -r '.explain.sessionSave')
echo "Journal directory: $JOURNAL_DIR"
echo "Include diff: $INCLUDE_DIFF"
echo "Session save: $SESSION_SAVE"