Big-Picture Synthesis
Target: $ARGUMENTS
Synthesizes a plan to plan — an overarching view across all Claude Code
artifacts. A reasoning tool that connects sessions, plans, tasks, and memories
into a coherent narrative of what you're working on, why, and where you're headed.
Arguments
| Position |
Name |
Required |
Default |
Description |
| 1 |
project-name |
no |
all projects |
Filter to a single project (substring, case-insensitive). Use all for all. |
| 2 |
time-range |
no |
all time |
E.g. 7d, 30d, this-week. |
| 3 |
output-path |
no |
auto |
Where to write output. |
Default output path:
project-name set: <decoded-project-path>/docs/bigpicture.md
all or omitted: ~/.claude/bigpicture.md
- Explicit
output-path: overrides both.
Project matching: Matched against decoded ~/.claude/projects/<encoded-path>/
directories (- → / in encoding). Substring match on any path segment.
Examples:
/synthesizing-cc-bigpicture # All → ~/.claude/bigpicture.md
/synthesizing-cc-bigpicture Agents-eval # Single → project docs/
/synthesizing-cc-bigpicture Agents-eval 7d # Single, last 7 days
/synthesizing-cc-bigpicture all 30d ./bigpicture.md # All, 30 days, custom path
Two Reasoning Axes
Track per work stream to surface where you are and what shift is needed.
Diverge / Converge
- Diverge: Expanding — brainstorming, exploring options, opening questions
- Converge: Narrowing — selecting approaches, committing, closing decisions
- Signals: Open questions in plans = diverging. Task completion clustering = converging.
- Alert: Diverging for N sessions without convergence → decision debt
Strategic / Tactical
- Strategic (top-down, deductive): Principles → plans → tasks. PRD → architecture → implementation.
- Tactical (bottom-up, inductive): Observations → patterns → principles. Bugs → learnings → plan revisions.
- Signals: PRD→task flow = strategic. AGENT_LEARNINGS, blockers→revisions = tactical.
- Alert: All strategic (no implementation feedback) or all tactical (reactive without direction)
When to Use
- Starting a work session — orient across projects
- Planning what to work on next — strategic prioritization
- Sprint/week boundary — maintain the meta-plan
- Feeling stuck — surface current reasoning mode and whether a shift is needed
Do Not Use
- Searching a specific past conversation (use
/resume or /history)
- Per-session context (session-memory does this automatically)
- Real-time usage monitoring (use
/insights)
CC Data Sources
~/.claude/
├── history.jsonl # Global prompt log (display, timestamp, project, sessionId)
├── stats-cache.json # Daily aggregates (messageCount, sessionCount, toolCallCount)
├── projects/<encoded-path>/
│ ├── memory/MEMORY.md # Per-project persistent knowledge
│ ├── <session-uuid>.jsonl # Full transcripts (metadata-scan only)
│ └── <session-uuid>/subagents/ # Subagent transcripts
├── plans/*.md # Plan mode files
├── tasks/<session-or-team-name>/ # Tasks (*.json, skip .lock/.highwatermark)
└── teams/<team-name>/ # config.json + inboxes/<member>.json
See references/cc-entry-types.md for JSONL entry type reference.
Project Filtering
When project-name is set (not all), ALL data collection and output must
respect the filter. Apply these rules once, consistently:
- Session allowlist: From
history.jsonl, collect sessionId values whose
project field matches (case-insensitive).
- Project dirs: Filter
~/.claude/projects/*/ to matching decoded paths.
- Plans: Content-based — include only plans mentioning the project name.
- Tasks: Match task dir names against session allowlist (UUIDs) or filtered
team names.
- Teams: Include only teams whose
config.json references the project name.
- Session .jsonl: Only read files whose UUID is in the session allowlist.
- Output: Every section scoped to filtered data only. Exception:
"Cross-Project Connections" may reference other projects as outbound links.
Workflow
Parse arguments — Apply defaults per Arguments table. Resolve output path.
Check existing — If bigpicture.md exists at output path, load for
incremental update (preserve structure, refresh content).
Discover & filter projects — Glob ~/.claude/projects/*/. Decode paths.
Apply project filter if set. Build session allowlist from history.jsonl.
Collect signals (sequential, metadata-first, no subagents):
- Activity:
stats-cache.json — daily counts for trajectory
- Sessions:
history.jsonl — unique sessionIds, timestamps, topics
- Memory:
projects/*/memory/MEMORY.md — persistent knowledge
- Plans:
plans/*.md — goals, open questions, decisions
- Tasks:
tasks/*/*.json — dependency graph, status
- Teams:
teams/*/config.json + inboxes/*.json — structure, comms
- Session metadata: First+last 5 lines of
.jsonl — timestamps, branches
- Project docs: Decoded project path →
CHANGELOG.md, AGENT_REQUESTS.md
Critical: Never bulk-read full .jsonl transcripts. Use history.jsonl
for discovery and first+last lines for metadata only.
Classify reasoning modes per work stream:
- Open questions vs. closed decisions → diverge/converge
- Plan-driven tasks vs. learning entries → strategic/tactical
- Flag imbalances (see alerts above)
Synthesize — Group by project → time clusters. Link plans↔sessions↔tasks.
Surface blockers, trajectory, recurring themes, cross-project connections.
Output using format below. Write to output path.
Output Format
# Big Picture — <date>
## Reasoning Mode Summary
| Project | Phase | D/C | S/T | Alert |
|---------|-------|-----|-----|-------|
## Active Work Streams
### <Project>
- **Status:** active/stalled — N sessions in last 7d
- **Focus:** <from memory + latest sessions>
- **Mode:** <diverging+tactical = exploring> | <converging+strategic = building>
- **Key decisions / Open questions:** <from plans>
- **Tasks:** N open / N total — blockers: <list>
- **Trajectory:** accelerating/steady/stalled
## Cross-Project Connections
## Active Plans
## TODOs & DONEs
## Blockers & Stale Items
## Mode Transitions Needed
Common Pitfalls
- Data dump: If output exceeds ~200 lines, raise abstraction. Interpret, don't list.
- Reading full transcripts: Use
history.jsonl + first/last lines only.
- False mode classification: Reasoning modes are heuristic signals, not verdicts.
- Spawning subagents: Don't. Sequential within fork context is sufficient.
Quality Check
- Correct > Complete > Minimal (ACE-FCA)
- ~100-200 lines output
- Every claim traces to a specific CC artifact
- Incremental update preserves structure, refreshes content
References
See references/cc-entry-types.md for JSONL session entry type taxonomy.
1---2name: synthesizing-cc-bigpicture-23description: Big-Picture Synthesis4---56# Big-Picture Synthesis78**Target**: $ARGUMENTS910Synthesizes a **plan to plan** — an overarching view across all Claude Code11artifacts. A reasoning tool that connects sessions, plans, tasks, and memories12into a coherent narrative of what you're working on, why, and where you're headed.1314## Arguments1516| Position | Name | Required | Default | Description |17|----------|------|----------|---------|-------------|18| 1 | `project-name` | no | all projects | Filter to a single project (substring, case-insensitive). Use `all` for all. |19| 2 | `time-range` | no | all time | E.g. `7d`, `30d`, `this-week`. |20| 3 | `output-path` | no | auto | Where to write output. |2122**Default output path:**23- `project-name` set: `<decoded-project-path>/docs/bigpicture.md`24- `all` or omitted: `~/.claude/bigpicture.md`25- Explicit `output-path`: overrides both.2627**Project matching**: Matched against decoded `~/.claude/projects/<encoded-path>/`28directories (`-` → `/` in encoding). Substring match on any path segment.2930**Examples:**3132```33/synthesizing-cc-bigpicture # All → ~/.claude/bigpicture.md34/synthesizing-cc-bigpicture Agents-eval # Single → project docs/35/synthesizing-cc-bigpicture Agents-eval 7d # Single, last 7 days36/synthesizing-cc-bigpicture all 30d ./bigpicture.md # All, 30 days, custom path37```3839## Two Reasoning Axes4041Track per work stream to surface where you are and what shift is needed.4243### Diverge / Converge4445- **Diverge**: Expanding — brainstorming, exploring options, opening questions46- **Converge**: Narrowing — selecting approaches, committing, closing decisions47- **Signals**: Open questions in plans = diverging. Task completion clustering = converging.48- **Alert**: Diverging for N sessions without convergence → decision debt4950### Strategic / Tactical5152- **Strategic** (top-down, deductive): Principles → plans → tasks. PRD → architecture → implementation.53- **Tactical** (bottom-up, inductive): Observations → patterns → principles. Bugs → learnings → plan revisions.54- **Signals**: PRD→task flow = strategic. AGENT_LEARNINGS, blockers→revisions = tactical.55- **Alert**: All strategic (no implementation feedback) or all tactical (reactive without direction)5657## When to Use5859- Starting a work session — orient across projects60- Planning what to work on next — strategic prioritization61- Sprint/week boundary — maintain the meta-plan62- Feeling stuck — surface current reasoning mode and whether a shift is needed6364## Do Not Use6566- Searching a specific past conversation (use `/resume` or `/history`)67- Per-session context (session-memory does this automatically)68- Real-time usage monitoring (use `/insights`)6970## CC Data Sources7172```73~/.claude/74├── history.jsonl # Global prompt log (display, timestamp, project, sessionId)75├── stats-cache.json # Daily aggregates (messageCount, sessionCount, toolCallCount)76├── projects/<encoded-path>/77│ ├── memory/MEMORY.md # Per-project persistent knowledge78│ ├── <session-uuid>.jsonl # Full transcripts (metadata-scan only)79│ └── <session-uuid>/subagents/ # Subagent transcripts80├── plans/*.md # Plan mode files81├── tasks/<session-or-team-name>/ # Tasks (*.json, skip .lock/.highwatermark)82└── teams/<team-name>/ # config.json + inboxes/<member>.json83```8485See `references/cc-entry-types.md` for JSONL entry type reference.8687## Project Filtering8889When `project-name` is set (not `all`), ALL data collection and output must90respect the filter. Apply these rules once, consistently:91921. **Session allowlist**: From `history.jsonl`, collect `sessionId` values whose93 `project` field matches (case-insensitive).942. **Project dirs**: Filter `~/.claude/projects/*/` to matching decoded paths.953. **Plans**: Content-based — include only plans mentioning the project name.964. **Tasks**: Match task dir names against session allowlist (UUIDs) or filtered97 team names.985. **Teams**: Include only teams whose `config.json` references the project name.996. **Session .jsonl**: Only read files whose UUID is in the session allowlist.1007. **Output**: Every section scoped to filtered data only. Exception:101 "Cross-Project Connections" may reference other projects as outbound links.102103## Workflow1041051. **Parse arguments** — Apply defaults per Arguments table. Resolve output path.1061072. **Check existing** — If bigpicture.md exists at output path, load for108 incremental update (preserve structure, refresh content).1091103. **Discover & filter projects** — Glob `~/.claude/projects/*/`. Decode paths.111 Apply project filter if set. Build session allowlist from `history.jsonl`.1121134. **Collect signals** (sequential, metadata-first, no subagents):114 - **Activity**: `stats-cache.json` — daily counts for trajectory115 - **Sessions**: `history.jsonl` — unique sessionIds, timestamps, topics116 - **Memory**: `projects/*/memory/MEMORY.md` — persistent knowledge117 - **Plans**: `plans/*.md` — goals, open questions, decisions118 - **Tasks**: `tasks/*/*.json` — dependency graph, status119 - **Teams**: `teams/*/config.json` + `inboxes/*.json` — structure, comms120 - **Session metadata**: First+last 5 lines of `.jsonl` — timestamps, branches121 - **Project docs**: Decoded project path → `CHANGELOG.md`, `AGENT_REQUESTS.md`122123 **Critical**: Never bulk-read full `.jsonl` transcripts. Use `history.jsonl`124 for discovery and first+last lines for metadata only.1251265. **Classify reasoning modes** per work stream:127 - Open questions vs. closed decisions → diverge/converge128 - Plan-driven tasks vs. learning entries → strategic/tactical129 - Flag imbalances (see alerts above)1301316. **Synthesize** — Group by project → time clusters. Link plans↔sessions↔tasks.132 Surface blockers, trajectory, recurring themes, cross-project connections.1331347. **Output** using format below. Write to output path.135136## Output Format137138```markdown139# Big Picture — <date>140141## Reasoning Mode Summary142| Project | Phase | D/C | S/T | Alert |143|---------|-------|-----|-----|-------|144145## Active Work Streams146### <Project>147- **Status:** active/stalled — N sessions in last 7d148- **Focus:** <from memory + latest sessions>149- **Mode:** <diverging+tactical = exploring> | <converging+strategic = building>150- **Key decisions / Open questions:** <from plans>151- **Tasks:** N open / N total — blockers: <list>152- **Trajectory:** accelerating/steady/stalled153154## Cross-Project Connections155## Active Plans156## TODOs & DONEs157## Blockers & Stale Items158## Mode Transitions Needed159```160161## Common Pitfalls162163- **Data dump**: If output exceeds ~200 lines, raise abstraction. Interpret, don't list.164- **Reading full transcripts**: Use `history.jsonl` + first/last lines only.165- **False mode classification**: Reasoning modes are heuristic signals, not verdicts.166- **Spawning subagents**: Don't. Sequential within fork context is sufficient.167168## Quality Check169170- Correct > Complete > Minimal (ACE-FCA)171- ~100-200 lines output172- Every claim traces to a specific CC artifact173- Incremental update preserves structure, refreshes content174175## References176177See `references/cc-entry-types.md` for JSONL session entry type taxonomy.