SourceAtlas: Smart Temporal Analysis (Git History) Skill

SourceAtlas: Smart Temporal Analysis (Git History)

Constitution: ANALYSIS_CONSTITUTION.md v1.0

Context

Analysis Scope: $ARGUMENTS (default: entire repository) Goal: Extract actionable insights from git history Time Limit: 5-10 minutes Prerequisite: code-maat (will ask permission to install if missing)

Quick Start

Check cache (skip if --force flag present)
Check code-maat installation (install if needed with permission)
Generate git log (last 12 months, code-maat compatible)
Run analyses: Hotspots, Coupling, Contributors
Risk assessment combining all dimensions
Generate report following output-template.md
Verify output using verification-guide.md
Auto-save to .sourceatlas/history.md

Your Task

You are analyzing git commit history to understand:

Hotspots - Files changed most frequently (likely complex/risky)
Temporal Coupling - Files that change together (hidden dependencies)
Recent Contributors - Who has knowledge of which areas (bus factor)
Risk Areas - Aggregate assessment for prioritization

What You'll Discover

| Analysis Type | Insight | Business Value | |---------------|---------|----------------| | Hotspots | Complexity indicators | Refactoring priorities, technical debt | | Coupling | Hidden dependencies | Architecture review targets | | Contributors | Knowledge distribution | Bus factor risks, training needs | | Risk | Aggregate assessment | Resource allocation decisions |

Core Workflow

Execute these steps in order. See workflow.md for complete details.

Step 0: Check Prerequisites (30 seconds)

Purpose: Ensure code-maat is installed and Java is available.

Check code-maat:

if [ -f "$HOME/.sourceatlas/bin/code-maat-1.0.4-standalone.jar" ]; then
  export CODEMAAT_JAR="$HOME/.sourceatlas/bin/code-maat-1.0.4-standalone.jar"
fi

If not found, use AskUserQuestion:

"code-maat required for analysis. Install now? (requires Java 8+)"
If yes → run ./scripts/install-codemaat.sh
If no → show manual installation steps

→ See workflow.md#step-0

Step 1: Generate Git Log (1 minute)

Purpose: Create code-maat compatible git log file.

Default: Last 12 months

git log --all --numstat --date=short \
    --pretty=format:'--%h--%ad--%aN' \
    --after="$(date -v-12m +%Y-%m-%d)" \
    > /tmp/git-history.log

If scope specified: Filter to directory (e.g., "src/")

→ See workflow.md#step-1

Step 2: Hotspot Analysis (2 minutes)

Purpose: Identify frequently changed files.

Run code-maat revisions:

java -jar "$CODEMAAT_JAR" -l /tmp/git-history.log -c git2 -a revisions

Calculate complexity scores: LOC × Revisions

Identify top 10 hotspots sorted by complexity

→ See workflow.md#step-2

Step 3: Temporal Coupling Analysis (2 minutes)

Purpose: Find files that change together.

Run code-maat coupling:

java -jar "$CODEMAAT_JAR" -l /tmp/git-history.log -c git2 -a coupling

Filter significant couplings: degree ≥ 0.5

Categorize: Expected vs Suspicious

→ See workflow.md#step-3

Step 4: Recent Contributors Analysis (2 minutes)

Purpose: Map knowledge distribution across modules.

Run code-maat entity-ownership:

java -jar "$CODEMAAT_JAR" -l /tmp/git-history.log -c git2 -a entity-ownership

Generate knowledge map by area (src/api/, src/core/, etc.)

Identify bus factor risks: Single-contributor modules

→ See workflow.md#step-4

Step 5: Risk Assessment (1 minute)

Purpose: Combine all dimensions into actionable priorities.

Calculate composite risk: (Revisions × Coupling_Count) / Contributor_Count

Risk categories:

Bus Factor Risk
Complexity Risk
Coupling Risk
Testing Gap Risk

→ See workflow.md#step-5

Output Format

Your analysis should follow this Markdown structure:

🗺️ SourceAtlas: History
───────────────────────────────
📜 [repo name] │ [N] months

**Analysis Period**: [start] → [end]
**Commits Analyzed**: [count]
**Files Analyzed**: [count]

## 1. Hotspots (Top 10)
[Table with Rank, File, Changes, LOC, Complexity Score]
[Insights paragraph]

## 2. Temporal Coupling (Significant Pairs)
[Table with File A, File B, Coupling, Co-changes]
[Expected vs Suspicious coupling analysis]

## 3. Recent Contributors (Knowledge Map)
[Per-area tables with Contributor, Commits, Last Active]
[Bus Factor Risks section]

## 4. Risk Summary
[Risk aggregation table]
[Priority Actions numbered list]

## 5. Recommendations
[Refactoring candidates, knowledge sharing, architecture review]

## Recommended Next
[Dynamic suggestions based on findings]

→ See output-template.md for complete specification and examples

Critical Rules

1. Privacy Aware

Use "Recent Contributors" not "Ownership %"
Focus on knowledge distribution, not blame
Frame findings as opportunities, not criticisms

2. Actionable Insights

Every finding must have recommended action
Reference specific commit counts and file paths
Provide concrete next steps (not vague suggestions)

3. Evidence-Based

All hotspot files must exist (verify)
Commit counts must match git history (±20% tolerance)
Contributor names must be in git log

4. Time-Bounded

Default: 12 months (good balance)
Minimum: 3 months (for meaningful patterns)
Maximum: 24 months (avoid ancient history)

5. Verification Required

Execute verification-guide.md after analysis
Verify file paths, commit counts, contributors
Correct discrepancies before output

6. Constitutional Compliance

Follow ANALYSIS_CONSTITUTION.md:

Article I: Evidence-based (all claims from git/code-maat)
Article III: Verification (run V1-V4 checks)
Article IV: Evidence format (file:line references)
Article V: Transparency (show analysis period, cache age)
Article VII: User Empowerment (actionable recommendations)

Self-Verification

After generating your analysis, execute verification steps:

Step V1: Extract Verifiable Claims

Parse output for all quantifiable claims:

File paths (hotspots, coupled files)
Commit counts (total, per file, per contributor)
Contributor names
Coupling pairs
Date ranges

Step V2: Parallel Verification

Verify hotspot files exist (sample 3-5)
Verify commit counts (±20% tolerance)
Verify contributors in git history
Verify coupling pairs (both files exist)
Verify date ranges within repository history

Step V3: Handle Results

✅ All checks pass → Proceed to output
⚠️ Minor issues (1-2 checks) → Correct and note
❌ Major issues (3+ checks) → Re-execute analysis

Step V4: Add Verification Summary

verification_summary:
  checks_performed: [...]
  confidence_level: "high"  # high|medium|low
  notes: [...]

→ See verification-guide.md for complete checklist

Advanced

Cache Behavior

Default: Use cache if exists
Force flag: Skip cache with --force
Cache location: .sourceatlas/history.md (fixed path)
Cache age warning: If >30 days old

→ See reference.md#cache-behavior

Auto-Save Mechanism

Complete Markdown report auto-saves after verification:

💾 Saved to .sourceatlas/history.md

→ See reference.md#auto-save-behavior

Handoffs to Next Commands

Based on findings, suggest:

High-risk hotspot → /sourceatlas:impact "[hotspot]"
Suspicious coupling → /sourceatlas:flow "[entry point]"
Refactoring needed → /sourceatlas:pattern "[pattern]"

→ See reference.md#handoffs

code-maat Installation

Default location: ~/.sourceatlas/bin/code-maat-1.0.4-standalone.jar
Auto-install via: ./scripts/install-codemaat.sh
Requires: Java 8+

→ See reference.md#code-maat-installation

Interpretation Guidelines

Hotspots: Not always bad (core logic changes often)
Coupling: Expected (same domain) vs Suspicious (cross-module)
Contributors: Healthy = 2-3 per module, Risk = single contributor

→ See reference.md#interpretation-guidelines

Support Files

Detailed documentation available in:

workflow.md - Complete Step 0-5 execution guide with bash commands
output-template.md - Full Markdown structure and examples
verification-guide.md - Self-verification steps V1-V4
reference.md - Cache, code-maat, interpretation, troubleshooting

Output Header

Start your output with:

🗺️ SourceAtlas: History
───────────────────────────────
📜 [repo name] │ [N] months

Then follow complete structure in output-template.md.

Agent Skills: SourceAtlas: Smart Temporal Analysis (Git History)

Install this agent skill to your local

Skill Files