crux-skill-memory-meditation-coordination

name

crux-skill-memory-meditation-coordination

description

File-based coordination primitives for meditation: artefact filename grammar (18 rows including `init-suggestions-{ts}.yml`, `finalisation-enhancements.yml`, per-tree ensemble variants, and 4 follow-up artefact types), placeholders, prefix-glob polling rule, never-hard-code invariant, retrospective template, Branch & Leaf Index template (single-model + ensemble variants). Use whenever the `crux-cursor-meditation-guide` agent reads, writes, or links a working-directory artefact.

CRUX Skill: Memory Meditation — Coordination

Implements all file-based coordination primitives for the meditation system: artefact filename grammar (18 rows post-richness), placeholder definitions, prefix-glob polling rule, never-hard-code report.{html,pdf} invariant, process retrospective template, Branch & Leaf Index template (single-model and ensemble variants), and the ensemble working-directory structure.

When to Use

Load this skill whenever the crux-cursor-meditation-guide agent:

• Reads, writes, or links any working-directory artefact
• Needs to poll for branch outputs or report files
• Needs to construct filenames from placeholders
• Needs to append the Branch & Leaf Index to facets.md
• Needs to write the process retrospective

This is the leaf utility skill — all five other meditation skills reference it for filename grammar and polling rules.

Artefact Filename Table (18 rows post-richness)

All artefacts in the meditation working directory follow these filename patterns:

Artefact	Filename pattern	Notes
Top-level facets (initial, pre-confirmation)	facets-pending-{ts}.yml	Deleted after the user confirms via combined Pattern-B askQuestion; schema extended to carry all 4 blocks (facets + sections + visualisations + additional_focus_areas)
Top-level facets (final, post-confirmation)	facets.md	Single navigational entry point; updated post-consolidation with the Branch & Leaf Index
Init suggestions (confirmed payload)	init-suggestions-{ts}.yml	Written by depth-0 manager during step 4b resume (after combined Pattern-B askQuestion resolves); schema: confirmed_sections + confirmed_visualisations + additional_focus_areas blocks; read by report-generation contract and adversarial reviewer Dim 13; linked from facets.md Branch & Leaf Index ## Top-level artifacts
Branch (depth 1, 2, 3)	branch-{N}-depth-{D}-sub-{S}-{slug}-{yyyymmddHHMMSS}.md	D ∈ {1,2,3}; S = 0 at depth 1, S ∈ {1,2,3} at depth 2, S ∈ {1,...,9} at depth 3
Branch (intermediate, Phase B working draft)	branch-{N}-depth-{D}-sub-{S}-{slug}-{ts}-findings.md	Research mode only; deleted after Phase G promotion
Peer review (Research mode)	branch-{N}-peer-review-{branchSlug}-{ts}.md	One per branch
Pending deep-facet confirmation request	pending-facets-branch-{N}-depth-{D}-sub-{S}-{ts}.yml	Only when confirmDeepFacets ≠ none; D is the parent agent's depth
Confirmed deep-facet response	confirmed-facets-branch-{N}-depth-{D}-sub-{S}-{ts}.yml	Same path-id and {ts} as the pending file
Adversarial review iteration	review-pre-report-{ts}-iter-{N}.md	N ∈ {1, 2, 3}; iteration cap
Finalisation enhancements (single-model)	finalisation-enhancements.yml	Written by depth-0 manager during step 8 consolidation reflection (in-pass, no extra read); top-5 ranked candidates; calling agent updates in place with accepted / treatment / decided_at_utc after Q-Finalisation-Enhancements resolves; linked from facets.md Branch & Leaf Index ## Top-level artifacts
Finalisation enhancements (ensemble per-tree)	{model-subdir}/finalisation-enhancements.yml	Written by per-tree depth-0 consolidation manager before returning to ensemble aggregator; carries source_tree: + surfaced_to_root: null placeholder (aggregator fills); NO per-tree askQuestion fires
Follow-up artefact: additional meditation	follow-up-meditation-{ts}.yml	Written by calling agent after Q-Finalisation-Enhancements resolves for additional_meditation items with treatment ∈ {queue, spawn_now}; {ts} is the calling-agent write timestamp
Follow-up artefact: extracted spec	follow-up-spec-{ts}.yml	Written by calling agent for extracted_spec items with treatment ∈ {queue, spawn_now}
Follow-up artefact: extracted memories	follow-up-memories-{ts}.yml	Written by calling agent for extracted_memories items with treatment ∈ {queue, spawn_now}
Follow-up artefact: expanded branch	follow-up-expansion-{ts}.yml	Written by calling agent for expanded_branch items with treatment ∈ {queue, spawn_now}
Process retrospective	retrospective-{ts}.md	One per meditation; process analysis separate from subject-matter outputs
Report HTML	report-{topic-slug}-{ts}.html	Shares {ts} with PDF pair
Report PDF	report-{topic-slug}-{ts}.pdf	Shares {ts} with HTML pair

Research-mode-only files (noted in table above): branch-*-findings.md (Phase B draft), peer-review files (branch-{N}-peer-review-*.md), facet-registry.yml (global facet allocation), citations-index.yml (append-only citation index), .facet-registry.lock/ (transient mkdir-mutex).

facets.md frontmatter — model strategy fields

When the depth-0 manager writes the final facets.md (step 4b promotion) and refreshes it post-consolidation (step 9 Branch & Leaf Index update), include the following fields in the frontmatter to record the resolved model strategy:

---
# ... existing facets.md frontmatter fields (topic_slug, mode, confirmed_at_utc, etc.) ...
model_strategy:
  mode: "none" | "random" | "per_branch" | "ensemble_max"
  resolved_model_slug: null | "<slug>"             # set when mode == "random"
  resolved_model_label: null | "<label>"
  branch_assignments: []                           # set when mode == "per_branch"
    # - branch_index: 1
    #   slug: "<slug>"
    #   label: "<label>"
  assignment_policy_note: null | "<note>"          # set when mode == "per_branch" and poolSize < branchCount
---

The model_strategy block is read by the report skill to drive per-branch attribution annotations and footer rendering. It is also read by the calling agent's step-10 presentation to surface the model strategy alongside the rest of the meditation outputs.

Placeholders

These placeholders are defined once here; all other meditation artefacts reference these definitions:

• {topic-slug} is the slug component of the working-directory name ({yyyymmdd}-{topic-slug}/) — extract as everything after the leading yyyymmdd-.
• {slug} (in branch filenames) is the kebab-case slug derived for that branch (depth 1) or that subfocus (depth 2/3); max 40 chars; lowercase; alphanumerics + hyphens only; stop-words stripped; the most meaningful 3–6 words.
• {ts} is the UTC timestamp yyyymmddHHMMSS captured at the moment the file is written: date -u +%Y%m%d%H%M%S.
• {N}, {D}, {S} are zero-padded numerals used as written above (branch-1, not branch-01).

Prefix-Glob Polling Rule (never equality)

Because the {slug} + {ts} suffix is not predictable until the writing agent commits the file, every polling agent must use prefix-glob matching:

# Branch-output polls
branch-{N}-depth-1-sub-0-*.md            # depth-1 outputs
branch-{N}-depth-{D}-sub-{S}-*.md        # depth-D≥2 child outputs (one per child sibling-index)

# Peer review polls (Research mode)
branch-{N}-peer-review-*.md

# Report pair polls (verification gate)
report-{topic-slug}-*.html
report-{topic-slug}-*.pdf

# Pending deep-facet confirmation polls (depth-0 manager, when confirmDeepFacets ≠ none)
pending-facets-*.yml

Use ls -1t <workingDir>/<glob> 2>/dev/null | head -n 1 to resolve the latest matching artefact when multiple regenerations have occurred (relevant for reports and review iterations).

Never hard-code these names. All references in this document, in the agent definition, and in the Branch & Leaf Index match these files via the prefix glob report-{topic-slug}-*.html / report-{topic-slug}-*.pdf. Never hard-code report.html / report.pdf.

Process Retrospective Template

Filename: retrospective-{yyyymmddHHMMSS}.md — use the same {ts} as the report pair when one was generated, or capture a fresh UTC timestamp if no report was produced (on ESCALATE).

Always written, including on ESCALATE (process analysis is especially valuable when the review cycle failed).

---
mode: "research" | "quick"
topic_slug: "{topic-slug}"
generated_utc: "2026-05-17T12:34:56Z"
verdict: "PASS" | "PASS_WITH_ADVISORIES" | "ESCALATE"
---

## Process Retrospective — {topic title}

### Summary Statistics
- **Mode**: Research | Quick
- **Total agents spawned**: {count} (N depth-1 + N depth-2 + N depth-3 + N peer-review + N adversarial-review iterations)
- **Branch files produced**: {count} ({breakdown by depth})
- **Peer reviews**: {count} (Research mode) | N/A (Quick mode)
- **Adversarial review iterations**: {count}, final verdict: {verdict}
- **MUST_FIX findings**: {total found} → {applied} auto-fixed, {escalated} user-escalated, {unresolved} unresolved
- **SHOULD_FIX findings**: {total found} → {applied} auto-fixed
- **ADVISORY findings**: {total found}
- **Missing slots**: {list or "none"}
- **Facet regeneration attempts**: {count} (0 = confirmed on first try)
- **Deep-facet confirmations**: {count} (0 = confirmDeepFacets was "none")

### What Went Well
{Substantive observations about the process — not generic praise. Examples:}
- Which branches produced the richest findings and why
- Whether the facet partitioning created clean, non-overlapping exploration paths
- Effective cross-branch convergences discovered independently
- Citation coverage completeness
- Where peer review added genuine value (Research mode)
- How well the adversarial review caught real issues vs false positives

### What Could Be Improved
{Honest assessment of process weaknesses. Examples:}
- Branches or depth-2/3 nodes that produced thin or repetitive content
- Facet partitioning problems (overlap, gaps, one facet too broad)
- Citation gaps or weak sourcing patterns
- Adversarial review findings that should have been caught earlier
- Any ESCALATE causes and whether they were avoidable
- Coordination issues (stale locks, slow polling, missing files)
- Depth-3 leaves that added little incremental value over their depth-2 parent
- Whether Quick mode would have been sufficient (if Research was used) or vice versa

### Structural Observations
{Analysis of the research tree's shape and efficiency:}
- Branch balance — did all 3 branches produce comparable depth and quality?
- Depth utility — did depth-3 add meaningful detail beyond depth-2?
- Peer review impact — what fraction of peer-review findings changed the consolidation? (Research mode)
- Adversarial review efficiency — how many iterations were needed and could the first pass have been cleaner?
- Subject-matter focus compliance — were there process-language violations that needed fixing?

### Recommendations for Future Meditations
{Actionable suggestions for improving the next meditation on a similar topic:}
- Facet suggestions if the topic were re-explored
- Mode recommendation (Research vs Quick) for this topic's complexity level
- Areas where deeper exploration (4+ depths or more branches) would have helped
- Areas where the tree was over-provisioned

The depth-0 manager fills in every section with specifics from the actual meditation run. Generic or placeholder content is not acceptable.

Branch & Leaf Index Template (Single-Model Variant)

After consolidation completes, the depth-0 manager must update facets.md by appending this Branch & Leaf Index section. Glob the working directory for actual filenames rather than reconstructing names from memory. Use relative paths (no ./ prefix needed).

Construction rule: glob the working directory for actual filenames (branch-*-depth-*-sub-*-*.md, branch-*-peer-review-*.md, review-pre-report-*-iter-*.md, confirmed-facets-*.yml, the latest report-{topic-slug}-*.html / report-{topic-slug}-*.pdf pair). Resolve {topic-slug} from the working-directory name and resolve {ts} placeholders by globbing for actual on-disk files. Never write literal {topic-slug}-{ts} placeholder text into facets.md.

Required structure (appended below the existing facets.md frontmatter and content):

---
(existing facets.md frontmatter / content above this line is unchanged)
---

## Branch & Leaf Index

### Branch 1 — {branch-1 facet title}
**Subfocus**: {one-line facet description}
**Model**: {branch-1 model label} _(only when `modelStrategy.mode == "per_branch"`; for `random` show `model_strategy:` line under `### Index metadata` instead)_

- **Depth 1 (root)**: [{branch-1-slug}](branch-1-depth-1-sub-0-{branch-1-slug}-{ts}.md)
- **Depth 2** (3 subfocuses):
  - [Sub 1 — {d2-sub-1-slug}](branch-1-depth-2-sub-1-{d2-sub-1-slug}-{ts}.md)
  - [Sub 2 — {d2-sub-2-slug}](branch-1-depth-2-sub-2-{d2-sub-2-slug}-{ts}.md)
  - [Sub 3 — {d2-sub-3-slug}](branch-1-depth-2-sub-3-{d2-sub-3-slug}-{ts}.md)
- **Depth 3** (up to 9 leaves):
  - Under D2-sub-1:
    - [Sub 1 — {slug}](branch-1-depth-3-sub-1-{slug}-{ts}.md)
    - [Sub 2 — {slug}](branch-1-depth-3-sub-2-{slug}-{ts}.md)
    - [Sub 3 — {slug}](branch-1-depth-3-sub-3-{slug}-{ts}.md)
  - Under D2-sub-2: ...
  - Under D2-sub-3: ...
- **Peer review** (Research mode only): [branch-1 peer review](branch-1-peer-review-{branch-1-slug}-{ts}.md)

### Branch 2 — ...
### Branch 3 — ...

### Top-level artifacts
- [Consolidation](consolidation.md)
- [Process Retrospective](retrospective-{ts}.md)
- [Report (HTML)](report-{topic-slug}-{ts}.html)
- [Report (PDF)](report-{topic-slug}-{ts}.pdf)
- Adversarial review iterations (one entry per `review-pre-report-*-iter-*.md` discovered):
  - [Review iter 1](review-pre-report-{ts}-iter-1.md)
  - [Review iter 2](review-pre-report-{ts}-iter-2.md) _(only if iteration 2 ran)_
  - [Review iter 3](review-pre-report-{ts}-iter-3.md) _(only if iteration 3 ran)_
- Facet confirmation trail (one entry per pending/confirmed pair discovered):
  - [Confirmed facets — branch 1 depth 1 sub 0](confirmed-facets-branch-1-depth-1-sub-0-{ts}.yml) _(only when `confirmDeepFacets ≠ none`)_
  - …
- [Facet registry](facet-registry.yml) _(Research mode only)_
- [Citations index](citations-index.yml) _(Research mode only)_
- [Init suggestions](init-suggestions-{ts}.yml)
- [Finalisation enhancements](finalisation-enhancements.yml) _(only when written by depth-0 consolidation reflection)_
- Follow-up artefacts (one entry per `follow-up-{type}-{ts}.yml` discovered):
  - [Follow-up: additional meditation — {title}](follow-up-meditation-{ts}.yml) _(only if present; treatment: queue)_
  - [Follow-up: extracted spec — {title}](follow-up-spec-{ts}.yml) _(only if present)_
  - [Follow-up: extracted memories — {title}](follow-up-memories-{ts}.yml) _(only if present)_
  - [Follow-up: expanded branch — {title}](follow-up-expansion-{ts}.yml) _(only if present)_

### Index metadata
- **Generated**: {ISO 8601 timestamp of index update}
- **Mode**: `research` | `quick`
- **Model strategy**: `none` | `random ({label})` | `per_branch (b1: {label}, b2: {label}, b3: {label}, …)` | `ensemble_max (member: {label})` _(line ALWAYS written; values reflect `modelStrategy.mode` and any resolved per-branch assignments / picked model from the depth-0 manager's in-memory `modelStrategy`)_
- **Total files indexed**: {count}
- **Missing slots**: {list any branch/depth/sub combinations that did not produce a file, or "none"}

Conventions:

• Display label of each link is the file's subfocus_slug from frontmatter, prefixed with the local sub-index.
• Group depth-3 leaves under their depth-2 parent. Sibling indices 1–3 belong to D2-sub-1, 4–6 to D2-sub-2, 7–9 to D2-sub-3.
• If a slot didn't produce a file, omit the link AND list the slot under "Missing slots".
• The "Top-level artifacts" subsection always lists consolidation.md, retrospective-{ts}.md, plus the latest report HTML/PDF pair (when generated), every review iteration discovered, and every confirmed-facets pair discovered. Registry / citations-index lines appear only in Research mode.
• Quick mode produces the same index minus per-branch "Peer review" lines and the two Research-only registry / index lines.
• When the adversarial review verdict was ESCALATE the report HTML / PDF lines are omitted (no report was generated), but every review-pre-report-*-iter-*.md is still linked.
• Pending coordination files (facets-pending-*.yml and pending-facets-*.yml) are not linked from the index; only the corresponding confirmed counterparts are linked.
• The per-branch **Model**: line appears only when modelStrategy.mode == "per_branch". For mode ∈ {"none", "random", "ensemble_max"} the per-branch model line is omitted (a single tree-wide model — or no model override — is recorded in the Model strategy line of "Index metadata" instead).

Branch & Leaf Index Template (Ensemble Variant)

For ensemble meditations, the ensemble root facets.md (shared, bare — no Branch & Leaf Index) is supplemented by per-model facets.md files (each with its own Branch & Leaf Index in the standard single-model format above). The ensemble report filenames are handled by the ensemble working-directory structure below.

Ensemble Working-Directory Structure

meditations/{yyyymmdd}-{topic-slug}-ensemble/
├── facets.md                                    # shared confirmed facets (bare — no Branch & Leaf Index)
├── finalisation-enhancements.yml                # root combined YAML written by aggregator (step 3d)
├── cross-model-synthesis.md                     # aggregation output
├── ensemble-report-{topic-slug}-{ts}.html       # ensemble-level report
├── ensemble-report-{topic-slug}-{ts}.pdf        # ensemble-level PDF
├── model-gpt-5.5/                               # complete meditation tree for GPT 5.5
│   ├── facets.md                                # per-model copy with Branch & Leaf Index
│   ├── consolidation.md
│   ├── finalisation-enhancements.yml            # per-tree YAML written by per-tree depth-0 manager
│   ├── facet-registry.yml                       # Research mode only
│   ├── citations-index.yml                      # Research mode only
│   ├── branch-*-depth-*-sub-*-*.md
│   ├── branch-*-peer-review-*.md                # Research mode only
│   ├── review-pre-report-*-iter-*.md
│   ├── retrospective-{ts}.md
│   ├── report-{topic-slug}-{ts}.html
│   └── report-{topic-slug}-{ts}.pdf
├── model-opus-4.7/                              # complete meditation tree for Opus 4.7
│   └── ...same structure...
└── model-gemini-pro-3.1/                        # complete meditation tree for Gemini Pro 3.1
    └── ...same structure...

Subdirectory names use the kebab-case version of each model's label from cruxMemories.meditate.modelPool, prefixed with model- (e.g. model-gpt-5.5, model-opus-4.7, model-gemini-pro-3.1).

Ensemble filename conventions:

Artefact	Filename pattern	Location
Shared facets	facets.md	Ensemble root
Root combined finalisation enhancements	finalisation-enhancements.yml	Ensemble root
Per-tree finalisation enhancements	{model-subdir}/finalisation-enhancements.yml	Per-model subdir
Per-model tree	model-{label-slug}/	Ensemble root
Cross-model synthesis	cross-model-synthesis.md	Ensemble root
Ensemble report HTML	ensemble-report-{topic-slug}-{ts}.html	Ensemble root
Ensemble report PDF	ensemble-report-{topic-slug}-{ts}.pdf	Ensemble root

Per-model subdirectories follow the standard single-model Coordination Conventions for all internal files.

Cross-Skill References

This skill is the leaf utility — all five other meditation skills reference it:

• crux-skill-memory-meditation-research — filename grammar for init-suggestions-{ts}.yml, Phase B draft files, facet-registry.yml, citations-index.yml, peer review files; polling loop; lock semantics
• crux-skill-memory-meditation-quick — filename grammar for branch outputs, polling loop
• crux-skill-memory-meditation-ensemble — ensemble working-directory layout; per-tree finalisation-enhancements.yml filename row; root finalisation-enhancements.yml filename row
• crux-skill-memory-meditation-review — review-iteration filename row; Branch & Leaf Index links review iterations
• crux-skill-memory-meditation-report — report filename grammar (never hard-code report.html/report.pdf); fresh-timestamp respawn rule; prefix-glob latest-wins