/schematic

name: schematic
description: |
  Reverse engineer a detailed product and technical specification document from a git branch's
  implementation. Use when: (1) a branch has shipped or is in-progress and needs documentation,
  (2) you need to understand what a branch does at product and architecture level, (3) onboarding
  to someone else's feature branch, (4) creating PR descriptions or design docs after the fact,
  (5) user asks to "analyze this branch", "write a spec from the code", or "document what this
  branch does". Produces a structured markdown spec covering problem statement, product requirements,
  architecture, technical design, file inventories, testing strategy, rollout plan, and risks.
author: Codex
version: 1.0.0
date: 2026-02-15
tags: [documentation, git, branch-analysis, spec, reverse-engineering]

Reverse Engineer Spec from Branch Implementation

Problem

Feature branches often ship without comprehensive documentation. After the fact, teams need product specs, architectural docs, or onboarding materials that explain what was built and why. Manually reading every file change is slow and error-prone. This skill systematically extracts a complete spec from a branch's diff.

Context / Trigger Conditions

• User asks to "analyze this branch" or "reverse engineer a spec"
• User asks to "document what this branch does"
• User wants a product spec, technical spec, or design doc from existing code
• A branch has many commits and files changed and needs a coherent explanation
• Onboarding to an unfamiliar feature branch

Solution

Phase 1: Scope the Branch

Get the full picture of what changed before reading any files.

# 1. Identify the base branch (usually main or latest)
git log --oneline <base>..HEAD | head -50

# 2. Get file-level diff stats
git diff --stat <base>...HEAD

# 3. Count the scale
git diff --stat <base>...HEAD | tail -1

**Hitchhiker commit detection (CRITICAL)**: Before proceeding, check whether the branch contains commits from other PRs that were separately merged to the target branch. This is common on un-rebased branches.

# Get PR commits from GitHub (if a PR exists)
BRANCH_NAME=$(git branch --show-current)
ALL_COMMITS=$(git log --oneline <base>..HEAD | wc -l)
PR_SHAS=$(gh pr list --head "$BRANCH_NAME" --json commits --jq '.[0].commits[].oid' 2>/dev/null)
PR_COMMIT_COUNT=$(echo "$PR_SHAS" | grep -c . 2>/dev/null || echo 0)

# If counts differ, scope to PR-only files
if [ -n "$PR_SHAS" ] && [ "$PR_COMMIT_COUNT" -lt "$ALL_COMMITS" ]; then
  echo "HITCHHIKER COMMITS: $ALL_COMMITS on branch, $PR_COMMIT_COUNT in PR"
  # Get files touched ONLY by PR commits
  PR_FILES=$(for sha in $PR_SHAS; do git diff-tree --no-commit-id --name-only -r "$sha"; done | sort -u)
  # Use: git diff <base>...HEAD -- $PR_FILES (simulates post-rebase diff)
fi

When hitchhiker commits are detected, use `git diff <base>...HEAD -- <PR_FILES>` for all subsequent analysis. State this scoping in the output. When not detected, use the full diff.

From the diff stats (scoped if needed), categorize files into groups:

• **Core implementation** (new modules, business logic)
• **Integration points** (modified selectors, reducers, hooks, components)
• **Tests** (unit tests, integration tests, e2e tests)
• **Configuration** (feature flags, env vars, types, configs)
• **Incidental** (formatting, imports, minor refactors)

Phase 2: Parallel Deep Exploration

Launch 2-4 parallel exploration agents, each focused on a different file group. This is critical for efficiency — reading 50+ files sequentially is too slow.

**Agent 1: Core Implementation**

• All new files (the heart of the feature)
• Focus on: purpose, key types, exported functions, data flow, inter-module connections

**Agent 2: Integration Points**

• Modified selectors, reducers, hooks, components
• Focus on: what changed, why (inferred), how it connects to core implementation

**Agent 3: Tests**

• All test files (unit, integration, e2e)
• Focus on: what behaviors are validated, key assertions, what product requirements they encode

**Agent 4 (if needed): Configuration & Infrastructure**

• Feature flags, env vars, build configs, type declarations
• Focus on: rollout strategy, gating mechanisms, deployment concerns

Each agent prompt should ask for:

• Purpose of each file
• Key exports and types
• Data flow and dependencies
• How each file connects to others in the group

Phase 3: Cross-Check for Gaps

After agents return, diff the analyzed files against the full file list:

# List all non-test changed files
git diff --stat <base>...HEAD -- '*.ts' '*.tsx' | awk '{print $1}' | sort

# Show small diffs for any files not yet analyzed
git diff <base>...HEAD -- <uncovered-files>

Read the remaining small diffs directly. These often contain important details:

• Type declarations (new fields on models)
• Feature flag definitions
• Bug fixes discovered during development
• Proxy/compatibility changes in existing code

Phase 4: Write the Spec Document

Structure the spec with these sections (skip sections that don't apply):

# [Feature Name]
## Reverse-Engineered Product & Technical Specification

## 1. Problem Statement
Why this feature exists. What user/business pain it addresses.
Infer from the nature of the changes and any comments in the code.

## 2. Solution Overview
High-level description of the approach. Key design properties
(transparent, lazy, bounded, etc.).

## 3. Product Requirements
### 3.1 User-Facing Behavior
Table of requirements inferred from tests and UI changes.

### 3.2 Supported Workflows
List of workflows validated by tests.

### 3.3 Scope Boundaries
What is and isn't included.

## 4. Architecture
### 4.1 System Diagram
ASCII diagram showing component relationships and data flow.

### 4.2 Data Lifecycle
Step-by-step flow from initial state through steady state.

## 5. Technical Design
Subsections for each major design decision:
- Feature flags and gat