cartographer

Cartographer

Overview

Produce an intent-first decomposition of a PR plus local working tree changes. Treat "major features" as behaviorally coherent change components, not just folders or file types, and explain why each component exists, how it is implemented, and what it changes.

Always include:

• Committed branch diff churn.
• Uncommitted local churn (staged, unstaged, and untracked files).
• A persisted markdown report written to CARTOGRAPH.MD at the repository root.

Workflow

Step 1: Establish Analysis Scope

Resolve the base/head context first and use merge-base as the committed diff base.

TARGET_BRANCH="${1:-main}"
HEAD_REF=HEAD
BASE_REF=$(git merge-base "$TARGET_BRANCH" "$HEAD_REF")

Hitchhiker commit detection (CRITICAL): Before proceeding, check whether the branch contains commits from other PRs that were separately merged to the target branch.

ALL_COMMITS=$(git log --oneline "$TARGET_BRANCH..HEAD" | wc -l)
BRANCH_NAME=$(git branch --show-current)
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 [ -n "$PR_SHAS" ] && [ "$PR_COMMIT_COUNT" -lt "$ALL_COMMITS" ]; then
  echo "HITCHHIKER COMMITS DETECTED: $ALL_COMMITS on branch, $PR_COMMIT_COUNT in PR"
  PR_FILES=$(for sha in $PR_SHAS; do git diff-tree --no-commit-id --name-only -r "$sha"; done | sort -u)
fi

When hitchhiker commits are detected, scope the diff to PR files only. Otherwise use full BASE_REF..HEAD_REF.

Pull full file-level and hunk-level data:

# Committed branch range
git diff --numstat "$BASE_REF..$HEAD_REF"
git diff --name-status "$BASE_REF..$HEAD_REF"
git diff "$BASE_REF..$HEAD_REF"

# Local changes
git diff --numstat --cached
git diff --numstat
git diff --cached
git diff

# Untracked files
git ls-files --others --exclude-standard

Build one combined churn dataset: committed + staged + unstaged + untracked.

Step 2: Infer Intent and Implementation Signals