| name | cross-project-process-miner |
| description | Aggregates session data from every project slug in ~/.claude/projects/ and surfaces systemic process patterns that appear in 3+ different projects, producing a prioritized finding list with project count, example evidence, and recommended fixes |
| aliases | ["cross-project-miner","process-miner","systemic-pattern-miner","multi-repo-retro"] |
| category | Orchestration Framework |
| tags | ["cross-project","process-analysis","systemic-patterns","session-analysis","continuous-improvement","multi-repo"] |
| version | 1.0.0 |
| requiresTools | ["session_analyze_replay","session_work_ratio"] |
| resolutionHints | ["find process patterns across all my repos","which issues are systemic vs project-specific","cross-repo session analysis","global CLAUDE.md improvement candidates","universal process signals from session history","patterns that appear in multiple projects"] |
Cross-Project Process Miner
Purpose
The broadest view in the retrospective system: aggregates session data from every project slug in ~/.claude/projects/ and surfaces findings that appear in 3+ different projects. These are systemic process issues, not project-specific quirks, and they feed directly into global CLAUDE.md updates rather than per-repo fixes.
Where session-retrospective-miner answers "what happened in this project's recent sessions," this skill answers "which process problems show up everywhere, regardless of project type."
All Project Slugs ──► Cross-Project Process Miner ──► Systemic Findings
(~/.claude/ │
projects/) ▼
Patterns appearing in 3+ projects
│
▼
Global CLAUDE.md + skill updates
When To Use This Skill
Trigger it when:
- You suspect an efficiency problem is systemic rather than project-specific
- Planning a global CLAUDE.md refresh
- Before authoring a new top-level skill or guardrail
- After multiple per-project retrospectives surface the same kind of finding
- Quarterly process review across your full workspace
Prerequisites
This skill uses two MCP tools from EVOKORE-MCP plus direct JSONL parsing:
session_analyze_replay — tool usage + retry signals across session replay logssession_work_ratio — per-session work density
Both tools are available in EVOKORE v3.1+. Verify with discover_tools before running.
Input Parameters
min_projects_for_pattern: 3
time_window: "last-30-days"
focus: "all"
output_format: "report"
min_session_turns: 10
project_exclude: []
Data Sources
| Source | Location | Used For |
|---|
| Claude session JSONL | ~/.claude/projects/<slug>/*.jsonl | Per-project tool sequences, turn counts, commits |
| EVOKORE replay logs | ~/.evokore/sessions/*-replay.jsonl | Tool-call sequences for EVOKORE-tracked sessions |
| EVOKORE evidence logs | ~/.evokore/sessions/*-evidence.jsonl | Verified outputs and commit presence |
| EVOKORE hook log | ~/.evokore/logs/hooks.jsonl | Damage-control + purpose-gate fires |
Patterns Detected
1. Opening Read Pattern
Signal: sessions whose first 3 tool calls are all Read (no Bash, Edit, Write, Grep, or Glob).
Hypothesis: context was not established upfront; the session is exploring instead of executing.
Severity: HIGH if affected sessions average 2x+ turns vs the project's median.
Fix template: "Open sessions with a targeted grep or nav_get_map call, not a series of exploratory reads."
2. Abandoned Session Pattern
Signal: sessions ending with 0 git commits and no @CreateDateColumn / migration / test output in evidence.
Hypothesis: exploration sessions that ran out of context or scope.
Severity: MEDIUM; HIGH if >15% of a project's sessions.
Fix template: "Set explicit session scope in the opening prompt, or use /compact + /clear to start a fresh focused session when exploring."
3. Agent Spawn Divergence Pattern
Signal: Agent / Task tool calls whose parent session has zero evidence entries attributable to that agent run.
Hypothesis: agents ran but produced nothing verifiable.
Severity: HIGH (agents are expensive).
Fix template: "All Agent spawn prompts should end with Output your result to [specific file or format]. Done when you have produced that output."
4. Bash Retry Spike Pattern
Signal: 3+ consecutive Bash tool calls with the same command shape, or Bash calls immediately followed by another Bash touching the same path/env.
Hypothesis: path/env fragility, usually Windows D:/ vs /d/ or .cmd suffix issues.
Severity: MEDIUM; HIGH if concentrated in Windows projects.
Fix template: "Add path handling to the relevant guardrail skill or CLAUDE.md, e.g. use forward slashes in Bash, .cmd on Windows for npx."
5. Cross-Project Convention Violation Pattern
Signal: clarification turns asking the same kind of convention question across multiple projects (e.g. "should the PK be UUID or BIGSERIAL?", "should I commit the build output?", "which branch base do I use?").
Hypothesis: missing global conventions.
Severity: LOW per occurrence, but compounds over time.
Fix template: "Add a Global Conventions block to the top-level CLAUDE.md (or an AGENTS.md) covering the repeated question."
Execution Steps
Step 1: Enumerate project slugs
List every subdirectory of ~/.claude/projects/. Each directory name is a project slug (often a path-encoded repo path, e.g. <encoded-repo-path>). Filter out any slug in project_exclude.
Step 2: Sample sessions per project
For each slug:
- List all
*.jsonl files whose mtime falls inside time_window.
- Count lines and skip files with fewer than
min_session_turns * 4 lines (each turn emits ~4 JSONL entries on average).
- Record the project slug and the session file paths.
Step 3: Aggregate tool-call and efficiency metrics
For each sampled session, parse the JSONL and extract:
const entries = jsonl.lines.map(JSON.parse);
const toolSeq = entries.flatMap(e =>
(e.message?.content || [])
.filter(c => c.type === 'tool_use')
.map(c => c.name)
);
const firstProductiveTurn = entries.findIndex(e =>
e.message?.content?.some(c =>
c.type === 'tool_use' && ['Edit', 'Write', 'Bash'].includes(c.name)
)
);
const hasCommit = entries.some(e =>
e.message?.content?.some(c =>
(c.type === 'tool_use' && c.name === 'Bash' &&
/git\s+commit\b/.test(c.input?.command || '')) ||
(c.type === 'tool_result' && typeof c.content === 'string' &&
/\[[\w\-/]+\s+[0-9a-f]{7,}\]/.test(c.content))
)
);
const agentSpawns = entries.flatMap(e =>
(e.message?.content || [])
.filter(c => c.type === 'tool_use' && (c.name === 'Agent' || c.name === 'Task'))
);
const totalTurns = entries.filter(e => e.type === 'assistant').length;
Also call the MCP tools once per project with an appropriate project filter:
session_analyze_replay({ time_window, project_filter: <slug> })
session_work_ratio({ time_window, project_filter: <slug> })
Step 4: Apply pattern detectors
For each pattern listed above, classify every sampled session as match or no match. Bucket matches by project slug.
A pattern "appears in" a project if at least one session in that project matches it. A pattern is systemic when it appears in at least min_projects_for_pattern distinct projects.
Step 5: Compute impact per pattern
For each systemic pattern:
projects_affected = list of slugs where it matchedtotal_sessions_affected = count of matching sessions across all projectsavg_turn_penalty = mean totalTurns of matching sessions minus mean totalTurns of non-matching sessions in the same projectsseverity = HIGH | MED | LOW using the pattern's defined thresholds plus the measured turn penaltyimpact_score = total_sessions_affected * severity_weight where HIGH=3, MED=2, LOW=1
Sort findings by impact_score descending.
Step 6: Produce report
Render the output template. If focus is narrower than all, filter the report to the relevant pattern families (e.g. agent-spawns → patterns 3 only).
Step 7 (optional): Emit CLAUDE.md patch
If output_format: "claude-md-patch", emit a fenced-diff block for each finding's Fix template, formatted for direct paste into the top-level CLAUDE.md:
+ ## Global Process Conventions
+
+ - Open sessions with a targeted grep or nav_get_map, not a series of exploratory reads.
+ - All Agent spawn prompts must end with "Output your result to [specific file or format]."
+ - (etc.)
The patch is advisory — the operator must review and apply it manually.
Output Template
## Cross-Project Process Analysis: [time_window]
Generated: [ISO timestamp]
Tool: cross-project-process-miner v1.0
Projects scanned: N (after exclusions)
Sessions analyzed: M (after min_session_turns filter)
min_projects_for_pattern: 3
---
### Systemic Findings (sorted by impact score)
**Finding 1: [Pattern name] — HIGH**
Appears in: [projectA, projectB, projectC, projectD] (4 projects, 27 sessions)
Avg turn penalty: +14 turns vs non-matching sessions
Impact score: 81
Example evidence:
- `projectA/session-2026-04-03.jsonl` — first 3 calls: Read, Read, Read (first Edit at turn 9)
- `projectB/session-2026-04-05.jsonl` — first 4 calls: Read, Read, Read, Read (first Edit at turn 12)
- `projectC/session-2026-03-29.jsonl` — first 3 calls: Read, Read, Read (first Edit at turn 7)
→ Recommended fix:
Add to top-level CLAUDE.md:
"Open sessions with a targeted `grep` or `nav_get_map` call, not a series of exploratory Reads.
If you need orientation, use `nav_get_map` on the entrypoint file first."
---
**Finding 2: [Pattern name] — MED**
...
---
### Per-Project Pattern Matrix
| Project | Opening Read | Abandoned | Agent Divergence | Bash Retry | Conventions |
|-------------------|--------------|-----------|-------------------|------------|-------------|
| EVOKORE-MCP | yes | no | no | yes | no |
| Claudius-Maximus | yes | yes | yes | yes | yes |
| OCR_LOCAL | yes | yes | no | no | no |
| EDCTool | no | no | no | yes | no |
| ... | ... | ... | ... | ... | ... |
---
### Summary
- Total systemic findings: N
- HIGH severity: N
- MED severity: N
- LOW severity: N
- Estimated global turn savings if all HIGH fixes applied: ~X turns/session across matching projects
---
### Recommended CLAUDE.md Patch
(only populated when output_format: "claude-md-patch")
```diff
+ ## Global Process Conventions
+
+ - [fix template for finding 1]
+ - [fix template for finding 2]
+ - ...
---
## Integration With Other Skills
### session-retrospective-miner
The retrospective miner is single-project; this skill is cross-project. Run the retrospective miner first per project, then run this skill to check whether per-project findings actually reflect a systemic issue before patching a per-project CLAUDE.md.
### improvement-cycles
Cross-project findings belong to improvement-cycles Phase 1 at the **global** scope. Per-project findings should be triaged via `session-retrospective-miner` before escalating to this skill.
### AEP Align phase
Systemic findings feed into the Align phase when the scope is "global process" rather than a single milestone. The `output_format: claude-md-patch` option is designed to hand directly to Align.
### meta-improvement panel
Cross-project findings can be presented to the meta-improvement panel as "global narrative quality" evidence, complementing the panel's existing persona-quality review.
---
## Example Invocation
Run cross-project-process-miner for the last 30 days across all projects.
min_projects_for_pattern: 3
focus: all
output_format: report
Save the output to docs/session-logs/cross-project-retro-2026-04-10.md.
If any HIGH findings appear, rerun with output_format: claude-md-patch so I can paste
the diff into the top-level CLAUDE.md.
---
## Interpretation Guide
| Signal | Meaning | Action |
|--------|---------|--------|
| HIGH finding in 5+ projects | True systemic issue | Update global CLAUDE.md and audit top-level skills |
| HIGH finding in exactly 3 projects | Likely systemic | Update global CLAUDE.md, monitor for additional projects |
| MED finding in many projects | Process friction, not blocker | Add a note to global CLAUDE.md; defer guardrail work |
| No findings surface | Per-project retrospectives are the right tool | Stop here and use `session-retrospective-miner` |
| One project dominates a "systemic" finding | It's actually project-specific | Demote to per-project fix via `session-retrospective-miner` |
---
## Safety Rules
1. **Never auto-apply** the `claude-md-patch` output. The operator must review and paste it manually.
2. **Never modify** per-project CLAUDE.md files from this skill — that is the job of `session-retrospective-miner` and `narrative-quality-scorer`.
3. **Respect `project_exclude`** — some project slugs may contain sensitive session data the operator does not want mined.
4. **Minimum session filter is load-bearing.** Without `min_session_turns`, trivial sessions dominate the "opening Read" pattern and produce false positives.
5. **Cross-project findings require evidence from at least `min_projects_for_pattern` distinct slugs.** Do not emit a finding that only appears in one or two projects — surface those through `session-retrospective-miner` instead.
