Intent Leverage Audit

When to Use

When an agent or human wants to systematically validate that the highest-leverage intents in the Intent DB still match reality — not everything a project has decided matters equally; a promise about checkout or sign-in is worth checking before a promise about admin cosmetics. This audit works the highest-stakes, longest-unchecked intents first, instead of validating in whatever order they happen to sit in.

This is /alignment-harness:intent-validation-engine's sibling: validation asks "does this still match, for everything"; this audit asks "of everything that might not match, which would hurt most if left wrong" and works that list first.

Prerequisites

This skill reads from the Intent DB (/alignment-harness:intent-db, shipped as a local file store — intent.js next to that skill, no server or API key required). If your own project also runs its own database-backed intent store with a server API, you can point at that instead; nothing here depends on any particular vendor's routes — describe your own project's equivalent wherever this doc shows a generic example.

Leverage priority comes from matching each intent against your project's own risk table (alignment-harness risk-table show — the same categories the governer uses: payments, auth, messaging, core features scored highest; cosmetic/admin-only scored lowest). If you haven't confirmed a risk table yet (/alignment-harness:harness-setup, checkpoint 2), this audit still runs, using the general defaults, and says plainly that its priority ordering is "uncalibrated" until you confirm one.

The Atomic Loop

Step 0: List what's unscored, before anything else

Not every intent will have enough signal to rank. Before fetching a batch, count how many entries in the store have no clear risk category and no leverage signal at all, and say so up front — "N intents have no leverage signal and won't be prioritized by this audit" — rather than silently working only the subset that happens to be rankable and letting that read as a clean bill of health.

Step 1: Fetch Batch

Local store (default — works with nothing else installed):

node <path-to-intent-db-skill>/intent.js recent 50

Read each entry's tags and primaryIntent/uxPromises and match against your risk table's categories to derive a rough priority, then sort by that — highest-stakes first. Entries already re-confirmed recently (touched within your own chosen window, commonly 7 days) can be skipped for this pass.

If your project runs its own leverage-scored intent-db server, and it exposes a sort-by-leverage query and a per-intent alignment brief, use those instead of the local ranking above — the loop below is identical either way, only the fetch step's mechanics differ. Describe your own project's actual routes when you set this up; there's no universal path to assume.

If the batch returns 0 items, everything currently rankable has been checked recently. Done for now.

Step 2: For Each Intent — Audit

For each intent in the batch:

2a. Get the brief

node <path-to-intent-db-skill>/intent.js brief <slug>

This returns a compact summary with the core rules, "never do" constraints, and the WHEN/THEN UX promises for that intent — everything you need to check it without loading the full entry.

2b. Read the code

If the intent has file references:

• Read each referenced file
• Check: does the code still implement the UX promises?
• Look for intent-citation tags in the code that reference this intent (if your project uses them)

If no file references exist:

• Search the codebase for the intent's slug or title in code comments
• Grep for key terms from the intent's primaryIntent

2c. Assess alignment

Ask yourself:

• ALIGNED: Code matches all uxPromises. No violations found.
• VIOLATED: Code contradicts or doesn't implement a uxPromise. Describe which promise is broken and why.
• UNCLEAR: Not enough information to determine. File references may be stale or the intent may need updated references.
• STALE INTENT: The intent itself is outdated (references removed features, deprecated patterns, etc.)

Step 3: Mark Validated

If ALIGNED:

node <path-to-intent-db-skill>/intent.js touch <slug>

This refreshes the intent's timestamp so it drops out of the next batch and boosts it in search as something recently re-confirmed.

If VIOLATED, UNCLEAR, or STALE:

Still touch it (you DID check it), then file a finding.

If your project has its own proposal-tracking system (an admin UI, a database, a vault of review notes), file it there in whatever shape it expects, with the intent's slug, the specific UX promise that's broken, the affected files, and a priority carried over from the intent's leverage tier.

Otherwise, use the harness's own local record: alignment-harness records proposals prints the folder — write one markdown file per finding there, for example:

---
title: "Violation: <intent title>"
status: needs-review
type: bug-hypothesis
priority: <leverage tier: critical|high|moderate|low>
linkedIntent: <slug>
---

**Expected:** <the uxPromise that's broken>
**Actual:** <what the code does instead>
**Evidence:** <file:line or grep match>
**Who's affected:** <who hits this — e.g. all users at checkout, only one plan tier>

Show the person the path you wrote to.

For UNCLEAR or STALE intents (not code bugs, but intent hygiene issues): use the same file shape with type: intent-doc instead of bug-hypothesis, framed as a question about the intent rather than an accusation against the code.

Step 4: Repeat

Go back to Step 1. Intents you just touched will no longer appear in the next unvalidated batch (however long a re-confirmation window you're using). The list shrinks each cycle — if it isn't shrinking over multiple runs, something is wrong with how "already checked" is being read back; treat that as a bug in this audit's own bookkeeping, not a reason to keep re-auditing the same items forever.

Swarm Deployment Pattern (optional — off by default)

This is for a large backlog, not a typical fresh project. Only reach for it once you have a genuinely large pile of unvalidated, high-leverage intents:

1. Fetch batch of 10
2. Dispatch 10 parallel subagents (one per intent)
3. Each subagent runs Steps 2-3 independently
4. Parent collects results, logs summary
5. Fetch next batch, repeat

Preload each subagent with the brief from Step 2a (since subagents may not have the same tools available).

Output Format

After each batch, report:

## Leverage Audit Batch N
| # | Priority | Slug | Status | Finding | Record |
|---|----------|------|--------|---------|--------|
| 1 | critical | post-payment-registration-resilience | ALIGNED | Code correctly handles failed registration after payment | — |
| 2 | critical | auth-failures-fail-open-never-crash | VIOLATED | ErrorBoundary catches but doesn't redirect — infinite blank screen | filed: proposals/2026-.../auth-failures... |
...

Checked: X/10 | Violations: Y (findings filed) | Unclear: Z | Unscored (not in this run): N

Related Skills

• intent-alignment-audit — broader audit that cross-refs the intent DB vs code intent-citation tags vs test coverage
• api-alignment-check — validates API contracts match frontend expectations
• validate-against-live-data — pattern for checking code correctness against reality
• verify-ux-assignment-state — verify simulator paths still work
• how-to-submit-and-track-proposals — full findings workflow (create, claim, implement, close), if your project has one

Leverage Priority Reference (defaults — recalibrate against your own risk table)

Tier	What Lives Here
CRITICAL	Checkout, auth, payment safety — audit first
HIGH	Feature gates, upgrade flows, first experiences
MODERATE	Internal classification, communication
LOW	Analytics, infrastructure
NOISE	Admin cosmetics — audit last or skip

Success Signals

1. Fetch batch returns intents sorted highest-priority first, with unscored/unrankable ones named separately rather than silently dropped.
2. The "not checked recently" filter shrinks over repeated runs:
   • First run: returns unvalidated intents sorted by priority
   • After validation: those intents disappear from the query
   • Eventually returns an empty batch — everything currently rankable has been checked
3. Each touch/validate call actually updates the timestamp — confirm by re-running the fetch and seeing the entry drop out.
4. Audit report table appears after each batch.

Red Flags (Something's Wrong)

Symptom	Cause	Fix
Batch returns the same intents every run	The "already checked" write isn't being read back by the next fetch	Treat this as a bug in the audit's own bookkeeping — check that touch/validate actually updated the stored timestamp
Nothing ever gets prioritized	No risk table confirmed yet, or the store has no intents with matchable categories/tags	Run /alignment-harness:harness-setup checkpoint 2, or proceed on general-tier defaults and say so
Unscored intents silently missing from every report	Step 0 wasn't run, or its count wasn't surfaced	Always report the unscored count alongside the batch table
Agent skipping code reads	No file references on the intent	Fall back to grep for the slug/title in code comments

Self-Healing Directive

Skill files and agent tools are meant to be self-healing. If you are using a tool that appears to be broken or causing extra steps required, define the fix and propose deploying a sub agent to perform that fix. Do not silently work around broken tooling — fix it or flag it.