Produces grounding context summaries — directory structure, recent diffs, and file patterns — from local repository state, enabling more accurate architectural and implementation decisions. Use when: 'extract context from this repo', 'what changed since last session', 'understand the repo structure before writing a prompt', 'ground a refactor in actual code state'.
Produces grounding context summaries — directory structure, recent diffs, and file patterns — from local repository state, enabling more accurate architectural and implementation decisions. Use when: 'extract context from this repo', 'what changed since last session', 'understand the repo structure before writing a prompt', 'ground a refactor in actual code state'.
category
system-health
triggers
["extract context from this repo","what changed since last session","understand the repo structure before writing a prompt","ground a refactor in actual code state"]
tier
1
agents
["primary"]
tool_dependencies
["file_system","bash"]
inputs
[{"name":"repo_path","type":"string","description":"Path to the repository to extract context from","required":true}]
outputs
[{"name":"context_summary","type":"string","description":"Grounding context summaries with directory structure, recent diffs, and file patterns from local repository state"}]
Repo Context Sync
Efficiently sync with relevant parts of local repositories to ground reasoning in actual codebase state. This skill enables context-aware architectural decisions, refactoring, and implementation prompt writing by providing tools to clone, track changes, and extract patterns from repos.
I. The Philosophy: Grounding in Reality
Architectural decisions made in a vacuum are fragile. Implementation prompts written without understanding existing patterns create friction. The Repo Context Sync skill embodies grounding in reality — the practice of syncing with the actual codebase state before making decisions or writing specifications.
This is not about reading every file, but about surgical context extraction: identifying what matters for the task at hand, syncing only those parts, and integrating that context into reasoning. It transforms vague architectural discussions into grounded, actionable decisions.
II. When to Use This Skill
Trigger this skill when:
User mentions "repo", "repository", "codebase", "sync", "what changed"
Starting a conversation about refactoring, architecture, or design
Writing implementation prompts that need to follow existing patterns
User asks about specific repo directories (e.g., /00_Roadmap/, /02_Specs/)
Need to understand current state of a local codebase before a sprint
III. Core Workflow
1. Identify Context Need
Parse the user's request to determine:
Which repo(s) are relevant
Which directories matter for the task
What keywords indicate focus areas
Common patterns:
"refactor the agent routing" → Need /02_Specs/, /04_System/
"write implementation prompt for X" → Need existing code patterns
"what changed in the backend" → Need diff since last sync
Implementation agents typically have full repo access, so prompts should leverage that:
"Read /src/components/ to understand component patterns"
"Follow the same naming conventions as existing files"
"Integrate with existing state management in /src/store/"
IX. Best Practices
Efficiency
Only sync directories relevant to the task
Use sparse checkout for large repos
Cache context summaries (invalidate on sync)
Accuracy
Always fetch latest changes before generating context
Verify commit hashes in diff tracking
Cross-reference multiple files for patterns
Transparency
Show user what's being synced and why
Surface generated summaries for review
Log sync operations to session
Integration
Read reference docs to understand patterns
Follow existing conventions in repos
Update state file after each sync
X. Limitations
What This Skill Does
Efficiently clone/sync relevant repo parts locally
Track changes and generate diffs
Extract patterns and conventions
Provide grounded context for reasoning
What This Skill Doesn't Do
Automatically modify code
Make architectural decisions
Execute implementation tasks
Replace manual code review
Store full repo history (only relevant parts)
Push or sync state to remote services — all operations are local
XI. Troubleshooting
Issue: Sparse checkout not working
Solution: Ensure Git version is 2.25+ (sparse-checkout v2 feature)
Issue: Context mapper finds too many files
Solution: Use more specific keywords or limit to specific directories
Issue: Diff tracker shows no changes
Solution: Verify last_commit_hash is correct and repo has been fetched
Issue: Scripts fail with permission errors
Solution: Ensure scripts are executable (chmod +x)
Output
.diff_summary.md in the repo root: markdown summary of changes since the last sync (added, modified, deleted files; commit messages; statistics).
.context_summary.md in the repo root: file tree, detected stack, keyword-matched files, and summaries of top relevant files.
Updated .repo-sync-state.json at your workspace root recording the commit hash and sync timestamp.
Examples
Scenario 1: "Understand the Gateway repo structure before writing a spec" → sparse checkout of /02_Specs/ and /04_System/, context_mapper run with keywords "gateway routing middleware", .context_summary.md produced and read to ground the spec.
Scenario 2: "What changed in the backend since last session?" → diff_tracker run against the stored commit hash, .diff_summary.md produced showing 3 modified files in the routing layer and 1 new migration, architectural implications surfaced.
Edge Cases
If no commit hash is stored in .repo-sync-state.json, diff_tracker defaults to comparing the last 10 commits — note this default explicitly in the output so the user knows the baseline.
If sparse checkout pulls more files than expected (e.g., a directory contains deeply nested subdirectories), the context map may be large — apply keyword filtering to keep output focused.
Anti-Patterns
Running context_mapper without first fetching latest changes — generates context from a stale local clone, which can produce misleading architectural suggestions.
Using this skill as a replacement for reading the actual code — context summaries are grounding artifacts, not substitutes for reading critical files directly.
