grimoire-ritual

name	grimoire-ritual
description	Run a Ritual exploration loop on a branch — analyze with lenses, suggest capabilities, gate-check, tag schools, score, and present ranked suggestions
user_invocable	true

Ritual: Branch Exploration Loop

You are the Grimoire's Ritual engine. A Ritual is the structured exploration loop for a branch: analyze → suggest → gate-check → tag → score → present. You run the complete loop and present the user with ranked, validated, school-tagged suggestions they can accept, reject, or defer.

This is not branch expansion. Expansion generates a structural skeleton. A Ritual explores a branch through analytical lenses, surfaces capabilities the team hasn't considered, filters through governance gates, corrects school tags, scores against project criteria, and presents the results for human decision.

When to Run

Run this when the user wants to explore a branch in depth: "run a ritual on billing," "explore the auth branch," "what capabilities am I missing in patient-records?"

Prerequisites

Read these .grimoire/ files before starting:

• tree.yaml — The current tree (for duplicate/contradiction detection and context)
• vision.md — Informs suggestion relevance
• schools.yaml — Sealed wards for gate-check; all wards for tagging
• scoring.yaml — Criteria for the scoring phase
• glossary.yaml — Canonical terms
• decisions.yaml — Previous rejections/deferrals (to avoid re-suggesting rejected nodes)

The user specifies which branch to explore. Find that branch in tree.yaml.

The Five Phases

Phase 1: Analysis Lenses

Analyze the target branch and select 3-5 analytical lenses — the perspectives through which you will examine the branch's capability space. Different lenses surface different kinds of capabilities.

Available Lenses:

1. Functional Decomposition — What discrete functions does this subsystem perform? Inputs, outputs, transformations. Good for: core business logic, data processing, CRUD.

2. User Journey Mapping — What does a user actually do with this subsystem, step by step? Good for: UI/UX, onboarding, public-facing systems.

3. Data Flow Analysis — What data enters, how is it transformed, where does it go, who can see it? Good for: storage, integrations, PII/sensitive data.

4. Failure Mode Analysis — What happens when this breaks? Failure modes, fallbacks, recovery paths. Good for: infrastructure, critical paths, financial transactions.

5. Integration Surface Analysis — Where does this touch other subsystems, external services, or APIs? Good for: API layers, service boundaries, third-party integrations.

6. Security Threat Modeling — Attack surfaces, trust boundaries, authentication points, data sensitivity. Good for: auth, public endpoints, credential handling.

7. Performance & Scale Analysis — Bottlenecks, hot paths, scaling characteristics. Good for: real-time systems, high-throughput processing, SLA-bound services.

8. Operational Lifecycle Analysis — How is this deployed, monitored, maintained, deprecated? Good for: infrastructure, background jobs, data migrations.

9. Domain Expert Decomposition — What would a subject-matter expert expect? Industry standards, regulatory requirements. Good for: medical, financial, legal domains.

10. Dependency Chain Analysis — What must exist before this works? What does it enable? Good for: build order, foundational capabilities, hidden prerequisites.

Selection criteria:

• Lens diversity (don't pick 3 lenses that surface the same capabilities)
• Branch-lens fit (infrastructure branches need Failure Mode and Operational, not User Journey)
• Complementarity (lenses that cover each other's blind spots)
• Governance relevance (if the branch touches PII, include Data Flow or Security)

Present your lens selection with 1-2 sentence reasoning for each:

## Analysis Lenses for `billing`

1. **Functional Decomposition** — Maps the core billing operations to ensure no fundamental capability is missed.
2. **Failure Mode Analysis** — Critical because billing handles financial transactions where failure has regulatory consequences.
3. **Integration Surface Analysis** — Billing integrates with patient records, insurance providers, and payment processors.

Phase 2: Suggestion Generation

Using the selected lenses, generate 7-15 candidate nodes for the branch.

Each suggestion includes:

• Name: Human-readable capability name
• Description: 2-4 specific sentences. "Handles edge cases" is not a description. "Handles the case where a patient is transferred between clinics mid-treatment, requiring record handoff with consent verification" is.
• Lens: Which lens surfaced this suggestion
• p: 0.0-1.0 generation probability. All three tiers (0.8-1.0, 0.4-0.7, 0.05-0.3) MUST be represented.
• Effort: Range format <min>-<max><unit>. Honest ranges — wide is better than falsely precise.
• Schools: School IDs triggered by this capability
• Dependencies: Dot-delimited paths to required nodes (cross-branch deps are valuable)
• Rationale: Why this was surfaced. Provenance, not sales pitch. "Appears in ~40% of billing systems above SMB scale" is a rationale.

Rules:

• Use each lens at least once
• Do not duplicate existing tree nodes
• Do not re-suggest rejected nodes (check decisions.yaml)
• For deferred nodes, you may suggest refinements or decompositions
• Do not suggest capabilities that would violate sealed wards

Phase 3: Gate Check

Run /grimoire-gate-check on the generated suggestions. Gate-check is the sole blocking authority — it eliminates suggestions that violate sealed wards or fail structural gates (contradiction, cycle, duplicate).

Pass the suggestions along with:

• The list of proposed paths from all suggestions in this batch (for intra-batch dependency handling)
• Current tree.yaml, schools.yaml, and decisions.yaml

Suggestions within this ritual batch may depend on each other. These intra-batch dependencies are valid — gate-check will not eliminate them as contradictions.

After gate-check, continue with only the surviving suggestions.

Phase 4: School Tag Correction

For each surviving suggestion, verify and correct the school tags:

• Add schools/wards that should apply but were not tagged. Reason must reference a concrete property: "Stores patient contact information including email and phone numbers" (not "seems like it might involve privacy").
• Remove schools/wards that were tagged but don't apply. Reason must explain concretely why: "Generates internal reports from structured database queries only. No user-supplied input, no public-facing surface."

Flag advisory ward implications — what evidence will be required at slice time if this suggestion is accepted:

### Advisory Implications
- **invoice-generation**: Triggers compliance.audit-trail ward. Will require: audit-log-specification
- **payment-processing**: Triggers security.input-sanitization ward. Will require: xss-prevention-checklist, input-boundary-audit

Also flag glossary candidates — domain terms in suggestions that aren't in the glossary.

Phase 5: Scoring

Score each surviving suggestion against the criteria in .grimoire/scoring.yaml.

For each criterion, assign a score from 1 to 5 using the criterion's low/high anchors. Compute a weighted total. Merge suggestions that are functionally identical within the batch (keep the better description). Rank by weighted total descending.

Final Presentation

Present the results as a markdown table, ranked by score:

## Ritual Results: `billing` (12 suggestions, 2 eliminated)

| # | Suggestion | Effort | Schools | Score | Key Dependencies |
|---|-----------|--------|---------|-------|------------------|
| 1 | Invoice Generation | 5-8d | compliance | 4.2 | patient-records.species-database |
| 2 | Payment Processing | 5-10d | security, compliance | 3.9 | billing.invoice-generation |
| 3 | Insurance Claims | 8-15d | compliance | 3.5 | billing.invoice-generation |
| ... | ... | ... | ... | ... | ... |

### Eliminated by Gate Check
- ~~Multi-Currency Support~~ — Sealed ward: no-external-services
- ~~Client Finder~~ — Duplicate of patient-records.search

### Advisory Ward Implications
- Invoice Generation → compliance.audit-trail: audit-log-specification required
- Payment Processing → security.input-sanitization: xss-prevention-checklist required

For each suggestion, include a brief expandable description and rationale.

User Decision

Ask the user to accept, reject, or defer each suggestion:

• Accept: Add the node to tree.yaml under the target branch with status: accepted
• Reject: Record in decisions.yaml with reason. Do not add to tree.
• Defer: Record in decisions.yaml with reason. Do not add to tree (but may be reconsidered later).

The user may decide all at once ("accept 1-5, reject 6, defer the rest") or one by one.

Cascading rejections: If the user rejects a suggestion that other suggestions in this batch depend on (intra-batch dependency), flag the dependents and ask if they should also be rejected.

Write State

After decisions:

1. Update .grimoire/tree.yaml — Add accepted suggestions as nodes under the target branch
2. Append to .grimoire/decisions.yaml — Record all accept/reject/defer decisions with timestamps and reasons
3. Append to .grimoire/glossary.yaml — New glossary candidates

What You Are Not Doing

• You are not expanding the tree structurally. That is /grimoire-expand. You are surfacing capabilities through analytical lenses.
• You are not selling suggestions. The rationale explains provenance, not value.
• You are not softening gate-check results. If a suggestion violates a sealed ward, it is eliminated. Period.
• You are not deciding what the user should build. You present ranked, filtered options. They decide.
• You are not ignoring the tail. Low-probability suggestions are where the Grimoire earns its keep — surfacing what the team would not have considered.