From ctx
Enriches /ctx-architecture artifacts with GitNexus MCP data: verifies blast radius, execution flows, domain clustering, registration sites. Run after base architecture analysis for quantification.
npx claudepluginhub activememory/ctx --plugin ctxThis skill is limited to using the following tools:
Enrich existing architecture artifacts with verified data from
Builds and maintains ARCHITECTURE.md and DETAILED_DESIGN.md incrementally with coverage tracking. Principal mode analyzes vision, bottlenecks, gaps, and alternatives.
Scans codebase and generates high-level architecture graph as interlinked markdown files in docs/professor/architecture/. Use for new project analysis or significant changes.
Runs 7-phase analysis of TypeScript codebases using typegraph-mcp tools like ts_dependency_tree and ts_import_cycles, producing architectural report for onboarding or overviews.
Share bugs, ideas, or general feedback.
Enrich existing architecture artifacts with verified data from
code intelligence tools. This skill reads the output of
/ctx-architecture (which forces deep code reading) and layers
on quantified, graph-backed data that reading alone cannot
efficiently provide.
Reading first, tools second. /ctx-architecture produces
deep artifacts through forced code reading - no code intelligence
tools, no shortcuts. This skill runs AFTER that pass, using the
deep artifacts as a baseline. It verifies, quantifies, and extends
The separation exists because agents take shortcuts when code intelligence tools are available during analysis. A structural query returns an answer without opening the file - so the agent never discovers the operational details (defaults, timeouts, scale math, edge cases) that only emerge from line-by-line reading. The tool answers the question asked but prevents discovery of answers to questions never asked.
/ctx-architecture or /ctx-architecture principal has
produced artifactsnpx gitnexus analyze --embeddings completes on a project
that already has architecture artifacts/ctx-architecture - if no architecture
artifacts exist, run /ctx-architecture first/ctx-architecture in the same session without
user request - let the user review the base artifacts firstThe skill refuses to run if these are missing:
.context/ARCHITECTURE.md - the authoritative architecture map.context/DETAILED_DESIGN.md (or domain split files) - per-module
deep reference.context/map-tracking.json - coverage state and confidence scoresThe skill checks and warns if these are missing but proceeds without them:
.context/DANGER-ZONES.md - consolidated danger zones (if absent,
extracts from DETAILED_DESIGN.md danger zone sections).context/CONVERGENCE-REPORT.md - convergence state.context/ARCHITECTURE-PRINCIPAL.md - principal analysis.context/CHEAT-SHEETS.md - lifecycle flow cheat sheetsRead the required files listed above. If any required file is missing, stop and say:
Architecture artifacts not found. Run `/ctx-architecture` first
to generate the baseline, then run this skill to enrich it.
Check each tool silently:
GitNexus (required):
mcp__gitnexus__list_repos to verify connectionIf GitNexus is not connected or the project is not indexed:
GitNexus is not connected (or this project is not indexed).
This skill requires a code intelligence graph.
To set up: add the GitNexus MCP server, then run:
npx gitnexus analyze --embeddings
If the index is stale (commits after last index):
GitNexus index is slightly stale (last indexed: <date>,
<N> commits since). Proceeding - results may be incomplete
for recently changed code.
GitNexus index is stale (last indexed: <date>, <N> commits
since). Results would be unreliable.
Run `npx gitnexus analyze` to update, then re-run this skill.
Gemini Search (optional):
Read all architecture artifacts into context. Pay attention to:
map-tracking.jsonmap-tracking.jsonFor each danger zone identified in DANGER-ZONES.md (or extracted from DETAILED_DESIGN.md if no standalone file exists):
Run impact analysis on the named symbol:
mcp__gitnexus__impact({target: "<symbol>", direction: "upstream"})
Record blast radius:
Assign verified risk level:
Risk thresholds should consider repository scale. In a small repo (<1000 files), d=1=4 might be critical. In a large repo (>10k files), d=1=15 might be routine. When unsure, bias toward HIGH over MEDIUM.
Guidelines (adjust for scale):
Graph data is a lower bound, not ground truth. Dynamic dispatch, reflection, config-driven wiring, and runtime registration can make graphs incomplete. If blast radius seems suspiciously low for a symbol you know is critical from reading the code, flag:
Risk: HIGH (enriched <date> via GitNexus)
⚠ Possible undercount - dynamic or indirect usage suspected
Update DANGER-ZONES.md with enrichment data:
1. **<symbol>** - <original description>
- Blast radius: d=1: N, d=2: N, d=3: N
- Affected flows: <list of process names>
- Risk: HIGH (enriched 2026-03-25 via GitNexus)
- Modification advice: <updated based on blast radius>
Update the summary table with verified risk levels.
For each extension point identified in DETAILED_DESIGN.md module sections:
Query the call graph for registration patterns:
mcp__gitnexus__context({name: "<registration function>"})
Build a registration inventory:
Write or update .context/EXTENSION-POINTS.md:
# Extension Points
_Generated <date>. Enriched via GitNexus call graph analysis._
## Summary
| Pattern | Registration Function | Count | Files |
|---------|----------------------|-------|-------|
| <name> | <func> | N | N |
## By Pattern
### <Pattern Name>
Registration function: `<func>` in `<file>`
Registered implementations:
1. `<impl>` - `<file>:<line>`
2. ...
Unregistered (defined but not wired):
- `<impl>` - `<file>:<line>` (potential dead code or
conditional registration)
Read all processes from GitNexus:
READ gitnexus://repo/<name>/processes
Select the most significant flows (10-15). Prefer flows that:
Identify multi-flow hotspots - symbols that appear in 3+ execution flows are integration points worth knowing
Update CHEAT-SHEETS.md with an execution flow index:
## Execution Flow Index (via GitNexus)
_Enriched <date>. These flows are auto-detected from the call
graph and complement the manually written cheat sheets above._
| Flow | Steps | Entry Point | Key Symbols |
|------|-------|-------------|-------------|
| <name> | N | <entry> | <hotspot symbols> |
### Multi-Flow Hotspots
Symbols participating in 3+ flows (high-impact modification
points):
| Symbol | Flows | Location |
|--------|-------|----------|
| <name> | N | <file>:<line> |
Read auto-detected clusters from GitNexus:
READ gitnexus://repo/<name>/clusters
Read manual domain splits from DETAILED_DESIGN.md (the domain file index if split, or section headers if monolithic)
Compare - surface mismatches:
Write comparison to ARCHITECTURE-PRINCIPAL.md (if it exists) or print to terminal:
## Domain Clustering Comparison (enriched <date>)
| Manual Domain | GitNexus Cluster | Match | Notes |
|---------------|-----------------|-------|-------|
| <domain> | <cluster> | yes/partial/no | <mismatch detail> |
### Hidden Coupling (GitNexus groups, manual splits)
- <module A> ↔ <module B>: N calls between them, but in
separate manual domains
### Artificial Grouping (GitNexus splits, manual groups)
- <module A> and <module B>: 0 calls between them, but in
same manual domain
### Boundary Violations
If hidden coupling exceeds 10 calls between manually separated
domains, flag as:
⚠ Architectural boundary violation: <domain A> ↔ <domain B>
N cross-boundary calls - consider refactoring or redefining
the boundary.
For each module at confidence < 0.75 in map-tracking.json:
Run semantic queries for the module's key concepts:
mcp__gitnexus__query({query: "<module purpose or key concept>"})
Get context on key symbols:
mcp__gitnexus__context({name: "<key exported symbol>"})
Read process participation - which execution flows does this module participate in?
Update the module's DETAILED_DESIGN.md section with findings - callers, execution flow participation, cross-module relationships that reading alone may have missed
Update confidence score in map-tracking.json with
justification:
"<module>": {
"confidence": 0.7,
"notes": "Enriched via GitNexus: 12 callers found, participates in 3 flows. Bumped from 0.5.",
"enriched_at": "<ISO-8601>"
}
Only bump confidence if the enrichment genuinely improved understanding. Adding caller counts without comprehension does not justify a bump.
Litmus test: if the module's purpose cannot be restated in 1-2 sentences after enrichment, do NOT increase confidence. Numbers without narrative are noise.
Re-read map-tracking.json (source of truth) and regenerate
CONVERGENCE-REPORT.md with updated confidence scores and an
enrichment summary section:
## Enrichment Summary
_Last enrichment: <date> via GitNexus (index: <commit hash>)_
| Phase | Items Processed | Key Findings |
|-------|----------------|--------------|
| Danger zones | N entries | N upgraded to CRITICAL/HIGH |
| Extension points | N patterns | N registrations found |
| Execution flows | N flows indexed | N multi-flow hotspots |
| Clustering | N domains compared | N mismatches found |
| Shallow modules | N modules enriched | N confidence bumps |
All enrichment edits include a timestamp annotation:
(enriched <date> via GitNexus)
This allows /ctx-architecture on subsequent runs to distinguish
manual analysis from enrichment data.
Print a concise summary to the terminal:
Enrichment complete:
- Danger zones: N entries, N with blast radius data
- Extension points: N patterns, N total registrations
- Execution flows: N indexed, N multi-flow hotspots
- Clustering: N domains compared, N mismatches
- Shallow modules: N enriched, N confidence bumps
- Artifacts updated: DANGER-ZONES.md, EXTENSION-POINTS.md,
CHEAT-SHEETS.md, CONVERGENCE-REPORT.md, map-tracking.json
All changes are in-place edits to existing .context/ files
plus these standalone files:
| File | Created by | Updated by enrichment |
|---|---|---|
DANGER-ZONES.md | /ctx-architecture (principal) | Blast radius, risk levels |
EXTENSION-POINTS.md | This skill | Registration inventory |
CONVERGENCE-REPORT.md | /ctx-architecture | Updated scores, enrichment summary |
CHEAT-SHEETS.md | /ctx-architecture | Execution flow index |
ARCHITECTURE-PRINCIPAL.md | /ctx-architecture (principal) | Clustering comparison |
DETAILED_DESIGN.md | /ctx-architecture | Shallow module updates |
map-tracking.json | /ctx-architecture | Confidence bumps, enriched_at |
No new files are created beyond EXTENSION-POINTS.md (which only this skill produces).
(enriched <date>) entries for
the same symbol. Timestamp annotations make previous enrichment
data identifiable./ctx-architecture --principal
for a full "analyze + enrich" pipeline across sessions.After running, verify: