Skip to content

Context Pulse

/ritual context-pulse answers one question: can a reasoning system act safely on this yet?

The pulse computes a Reasoning Readiness score (0–100%) for a feature description or an existing exploration. Reasoning Readiness names how safely an intelligent interpreter (model, agent, or developer) can understand the task, inspect the environment, make decisions, and act without inventing consequential facts.

The inverse — Context Debt — is the same measurement framed as what’s still missing.

Why this metric exists

The Ritual product pitch in one line: AI made outputs easy, but drift and rework exploded. Ritual’s discovery-to-recommendations workflow builds clarity before context debt slows you down.

The pulse makes that pitch measurable. Instead of a vague claim that “the agent needs more context,” the pulse points at which dimensions are weak, which specific debt sources are biggest, and what the next action would do to the score.

Framing inspired by Karpathy’s observation that context is the programming surface for an intelligent interpreter. The right question isn’t “is the context complete?” — context can always be more complete. The right question is “is the context good enough for the interpreter to act correctly without inventing consequential facts?” Reasoning Readiness is that bar.

The four dimensions

The score is the weighted sum of four dimensions:

DimensionWeightWhat it measures
Feature clarity30%Is what “done” looks like written down? Acceptance criteria present? Anti-goals declared?
Decision resolution30%Open decisions named + resolved (recommended + accepted)? Or still floating?
Repo grounding25%Have the relevant files / modules been identified and mapped to the feature? Are prior decisions in this code area visible?
Assumption safety15%Risky assumptions called out vs hidden? Anti-goals declared so the agent knows what’s out of scope?

A typical “raw ask” pulse scores 15–25% (low across all four). A pulse after the discovery stage typically lands in the 50–60% range. A pulse after the build brief lands at 85–92% — the “Implementation-ready” tier.

The four modes

The pulse operates in four distinct modes based on the input. The agent picks the mode automatically by classifying what you pass it.

Mode A — Naked

/ritual context-pulse with no arguments and no in-flight exploration.

The codebase is “table stakes” — having one doesn’t move the score for a feature that hasn’t been described. The pulse returns a near-zero score and the recommended action: “Give me a feature description, or run /ritual build.”

Use when: experimenting with the command, or asking your agent to suggest where to focus.

Mode B — Cold-call feature

/ritual context-pulse "Add billing export for workspace admins" — a description with no matching exploration yet.

The agent maps the description to your codebase + workspace KG, finds candidate files and prior decisions that may collide, and offers to seed a CONTEXT-<feature-slug>.md file in your repo as a pre-build context starter. The mapping work is what moves Repo grounding — the codebase only counts once it’s been mapped to THIS feature.

Use when: you have a vague feature idea and want to know if it’s ready for /ritual build, or what’s blocking it.

Mode C — Existing exploration

/ritual context-pulse exp-7a2b9c (by exploration ID) or /ritual context-pulse "Conversion attribution" (by name lookup).

Fetches the exploration’s current state — answered questions, accepted recommendations, build brief status — and scores against that data. This is the standard mid-flow check.

Use when: you started a build, walked away, came back, and want to know where the exploration stands before continuing.

Mode D — Inline

Fired automatically inside /ritual build at the end of major stages (context, scope, discovery, recommendations, build brief). You don’t invoke these; they’re emitted as compact one-liners in the CLI as the stage loop progresses.

This is what makes “watch Readiness climb live” the product’s headline visual — each stage pays down debt visibly.

Output anatomy

A full pulse output (Mode B or C):

$ /ritual context-pulse "Add an AI assistant to the product"

  Reasoning Readiness    18 %
  Context Debt           82 %
  Context Surface        Raw ask

  Feature clarity        8 / 30
  Decision resolution    0 / 30
  Repo grounding         10 / 25
  Assumption safety      0 / 15

  Top debt sources:
    • No acceptance criteria — what does "done" look like?
    • 10 unresolved decisions across model, RAG, memory, UI, eval
    • 3 unverified assumptions about existing infra

  Next: /ritual build "Add an AI assistant to the product"

Reading it

FieldMeaning
Reasoning ReadinessThe headline score. 0% = the agent will guess at almost everything. 100% = every consequential fact is grounded; the agent can act without inventing.
Context DebtThe inverse. 100% – Readiness. Same number, different framing.
Context SurfaceA tier label: Raw ask (15–25%), Under-specified (25–45%), Exploration-safe (45–70%), Recommendation-ready (70–85%), Implementation-ready (85%+).
Per-dimension scoresOut of the dimension’s max weight. Helps you see where debt lives — feature clarity vs decision resolution vs grounding vs assumption safety.
Top debt sourcesConcrete gaps — specific questions unanswered, specific assumptions unchecked, specific files unmapped.
NextOne recommended next action. Always a concrete command. Never a vague “consider doing X.”

Inline pulse (compact)

The inline pulses inside /ritual build are tighter:

Reasoning Readiness  48% → 72%   (+24%)
Context Debt         52% → 12%   (–40%)        (4 questions unreviewed)
Context Surface      Recommendation-ready

Just the deltas and the new tier label. No per-dimension breakdown unless the score crossed a tier boundary (e.g. Exploration-safe → Recommendation-ready) or moved ≥15% in either direction.

How dimensions are scored

Scoring happens server-side via the score_context_pulse MCP tool. The formula is deterministic for reproducibility — same inputs produce the same score. Each dimension’s score is computed from MCP-tool-readable signals:

  • Feature clarity — presence of acceptance criteria; declared anti-goals; problem-statement structure; ambiguous terms flagged.
  • Decision resolution — number of open discovery questions vs answered; recommendations in draft vs accepted; deferred items classified.
  • Repo grounding — file paths mapped to the feature; KG entries for prior decisions in the same files; codebase patterns identified.
  • Assumption safety — flagged risky assumptions; anti-goal declarations; collision check against existing explorations.

When dimensions can’t be fully scored (e.g. no codebase context yet), the missing portion is debt, not skipped.

  1. Vague feature ask in your head. Run Mode B: /ritual context-pulse "<your description>". See where the debt is.
  2. Score below ~30%. Either reframe the description (acceptance criteria, anti-goals) and re-pulse, or run /ritual build — discovery will surface what’s missing structurally.
  3. Score 50–70%. You’re at Exploration-safe. /ritual build is appropriate; discovery + recommendations will move you to Recommendation-ready.
  4. Score 85%+. Implementation-ready. The build brief should reflect this — proceed to implementation with confidence.