Intent Lifecycle System

Overview

Intent is the single most fragile artifact in agentic coding. It gets stated once by the person, then diluted or lost as it passes through planning, code, tests, errors, commits, and audits. This skill treats intent as a first-class entity with a slug identifier that flows through every phase.

Core principle: If the person's original intent cannot be traced from their words to the deployed code, the system has failed — regardless of whether the code "works."

Intent statement format

REQUIRED: Before writing any intent statement, invoke /intent (the skill that defines system-intent and UX-intent formats, wrong/right examples, and the rules for translating code into human-readable statements without losing precision).

System: When {every condition, described as what's happening in the person's experience} then {the system responsible, named by what it does} should {the exact behavior, as its effect on the person}
UX: When {every condition, described as what the person has done or what state they're in} then {the person} should {exactly what happens for them, with code-level precision in human terms}

Rules

1. Never use code variable names when a UX-equivalent exists
   • Wrong: "when plan === 1 and stripeCustomerId exists"
   • Right: "when the user is not paying and not on a trial"
2. Not all code intent CAN be translated to UX — but never substitute a code variable for something that has a UX-equivalent expression
3. Each intent must be:
   • Atomic — one testable thing
   • Precise — as specific as code
   • Human-readable — any stakeholder can understand it

Examples

# Good — "When {constraints} we {statement}"
When a free user reaches the session limit, we show a clear upgrade prompt with pricing

When a paying user's token expires mid-session, we renew it silently — the session continues
without interruption

When a user who isn't paying or on a trial first lands on the home page, we do not force login

# Bad
When plan === 1 then show modal                    (code variables, not UX)
When user hits paywall then handle it               (vague, not testable)
When auth fails then retry and show error           (two things, not atomic)

One identifier per intent: the slug

Use one short, kebab-case, human-readable slug per intent (e.g. silent-session-renewal), assigned when it's first written down. This is what travels through code comments, test names, and commit messages — it's readable without a lookup, which matters, since carrying two different names for the same thing is exactly the kind of drift this skill exists to prevent. If your intent store assigns a numeric ID too (the intent-db skill's local store can), treat it as optional metadata, not the thing you carry through context.

Token budget: carry slugs through agent context (a few tokens each); fetch the full statement on demand when you actually need it. 50 intents referenced by slug in a plan costs a small fraction of what carrying every full statement would.

The seven phases

Phase 1: DISCOVERY (conversation)

Recognize intent markers in what the person says and decompose them into atomic statements.

Auto-mining triggers — when the person says any of these, an intent exists to be captured:

Pattern	Example	Intent Direction
"users should never..."	"users should never see a blank screen after paying"	Direct statement
"users should always..."	"users should always know their trial status"	Direct statement
"we intend to..."	"we intend to make onboarding zero-friction"	Strategic intent
"the user expects..."	"the user expects their session to persist"	UX contract
"when X happens, they should see Y"	"when they upgrade, they should see a confirmation"	Conditional UX
"never show X when Y"	"never show upgrade CTA to a paying user"	Negative constraint
"this should be invisible to the user"	"token refresh should be invisible"	Transparency constraint
"this is broken because [UX description]"	"this is broken because free users see paid features"	Inverse is the intent

Actions:

1. Decompose into atomic When...then... statements.
2. Assign a slug (kebab-case, 3-5 words, UX-descriptive).
3. Record it: node <intent-db-skill-path>/intent.js create '<json>' (see the intent-db skill — a local file store, no server or database needed). If you separately track business-strategy/KPI intents in something else, that's an optional add-on, not required for this to work.
4. Print slugs to chat — carry them forward through all phases.

Token cost: ~20 tokens per slug carried forward.

Phase 2: PLANNING

Plans explicitly reference the intent slugs they will address. Any known intent in the area NOT covered by the plan gets flagged as a gap.

Actions:

1. Search for relevant entries: node <intent-db-skill-path>/intent.js find "<feature area>".
2. List the intent slugs the plan will address in the plan header.
3. Flag any known intent in the area NOT covered by the plan.
4. If writing a plan doc, include an ## Intents Addressed section:

## Intents Addressed
- `silent-session-renewal` — Phase 3, Task 2
- `auth-api-credentials-include` — Phase 3, Task 1
- `upgrade-cta-never-shown-to-paying-user` — Phase 3, Task 4

## Intents NOT Addressed (known gaps)
- `session-history-persists-across-devices` — out of scope, logged for future

Token cost: 1 query, ~200 tokens for results.

If you have a plan-writing skill installed (e.g. superpowers-writing-plans-v2), use it for the plan's overall structure — this section only covers the intent-linkage part.

Phase 3: IMPLEMENTATION

Load only the 2-3 intents relevant to the current file/function. Tag code where behavior is non-obvious.

Code comments:

// @intent: silent-session-renewal
// When a paying user's token expires mid-session
// then the session continues without interruption
async function refreshTokenSilently() {
  // ...
}

Logs with intent tracing:

logger.warn('[auth] Token refresh failed — user will see re-login prompt', {
  intentSlug: 'silent-session-renewal',
  uxImpact: 'Session interrupted, user loses their place',
  userId: user._id,
});

Rules:

• Only tag where behavior is non-obvious or where a future agent might misunderstand WHY.
• Do not tag every line — tag entry points, gates, and error paths.
• Include a uxImpact field in error logs so monitoring surfaces UX consequences, not just technical failures.

Token cost: ~10 tokens per slug reference.

Phase 4: TDD

Test descriptions state the UX intent, not a cryptic function name. Test file headers list the intent slugs covered.

Test file header:

/**
 * @intents-covered: silent-session-renewal, auth-api-credentials-include
 *
 * Tests verify that token expiration during an active session is handled
 * invisibly to the user (no interruption, no re-login).
 */

Test descriptions:

// Good — states UX intent
test('S1: token expiration mid-session renews silently — user sees zero interruption', async () => { ... });

test('S2: when refresh fails, user sees a friendly re-login prompt — not a raw error', async () => { ... });

// Bad — cryptic function name, no UX context
test('refreshToken retries 3 times', async () => { ... });

If you have a TDD-discipline skill installed, use it for the RED-GREEN-REFACTOR cycle — this section only covers the intent-naming part.

Token cost: ~15 tokens per test description.

Phase 5: COMMIT

Commit messages reference the intent slugs addressed.

fix(auth): add credentials to login API calls

When login API calls omit credentials, cookie-based auth silently fails and
users see a blank screen after what appears to be a successful login.

Intents: auth-api-credentials-include, registration-stores-both-tokens

Rules:

• Intent slugs go in the commit body, not the subject line.
• Subject line follows conventional-commits format.
• Body explains the UX consequence of the bug/feature, not just the technical change.

Token cost: ~10 tokens per commit.

Phase 6: UX VERIFICATION

Each verification/test assignment validates the ORIGINAL intent — not a deviation from it.

## Assignment: Verify Silent Token Renewal
**Intent:** `silent-session-renewal`
**When:** User is mid-session and token expires
**Then:** Session continues without interruption — no modal, no redirect, no visible error

If you have a UX-assignment-generation skill installed, use it for the assignment mechanics — this section only covers the intent-linkage part. If you don't, a plain markdown list like the above is a complete substitute.

Token cost: 1 query per assignment.

Phase 7: AUDIT

Query the intent record to find gaps, measure velocity, and trace errors back to intent.

# Which intents have no TDD coverage?
node <intent-db-skill-path>/intent.js recent 50   # list slugs, then:
grep -r "@intents-covered" <repo> | grep -v "<slug found above>"   # slugs missing from any test header

# Which intents were addressed in the last two weeks?
git log --since="2 weeks ago" --grep="Intents:" --oneline

# Which logs reference this intent?
grep -r "intentSlug.*silent-session-renewal" <repo>

If you have a deeper cross-reference skill installed (intent-alignment-audit), use it for a fuller pass — this is the always-available minimum.

Token cost: 1 query per audit question.

Token budget strategy

Do not carry all intents in context. Make them queryable.

Artifact	Token Cost	Strategy
Slug only	~3-5 tokens	Carry freely in context
Full description	~50-100 tokens	Fetch on demand via intent.js get <slug>
Phase-gated set	~20-60 tokens	Only load intents for current phase + feature area

Phase-gated loading:

• Discovery: all intents for the conversation topic.
• Planning: all intents for the feature area (1 query).
• Implementation: only 2-3 intents for the current file.
• TDD: only intents relevant to the test file.
• Commit: only slugs (no full descriptions needed).

Opportunistic linkage — when to attach intent slugs

Intent linkage is conditional, not mandatory. A slug flows through whatever you naturally touch during work. If an intent surfaces, link it. If not, don't force it.

When to link:

• An intent is discovered or clarified during conversation → record it (Phase 1).
• Writing code that serves a known intent → // @intent: <slug> (Phase 3).
• Creating tests for intent-related behavior → @intents-covered header (Phase 4).
• Committing code with intent relevance → Intents: line (Phase 5).
• Creating a UX verification item → cite the slug (Phase 6).

When NOT to link:

• Pure maintenance/refactoring with no UX intent.
• Infrastructure changes (CI, tooling, deps).
• You don't know of a relevant intent and nothing surfaced during work.

If you track other systems that accept intent references (a changelog, a task tracker, a notifications system, whatever your project has), wire an intentIds/intentSlugs-style field into each — this is the general pattern; which systems you have is specific to your own project.

Quick Reference

Phase	Agent Action	Artifact Created
Discovery	Decompose speech into atomic intents	Intent DB entries with slugs
Planning	Search the intent store, reference slugs in plan	Plan with ## Intents Addressed
Implementation	Tag code with @intent: slug	Code comments, intentSlug in logs
TDD	Name tests after UX intent	@intents-covered headers, descriptive test names
Commit	Include slugs in commit body	Intents: slug-1, slug-2
UX Verification	Link the assignment to the intent slug	Assignment with intent linkage
Audit	Query for coverage gaps	Gap reports

Common Mistakes

Mistake	Fix
Carrying full intent descriptions through all phases	Carry slugs only. Fetch full descriptions on demand.
Writing intents with code variable names	Translate to UX language. plan === 1 becomes "free user."
Compound intents (two things in one statement)	Split. Each intent must be independently testable.
Tagging every line of code with @intent	Tag entry points, gates, and error paths only.
Skipping Phase 1 decomposition ("I know what they mean")	Always decompose explicitly. Implicit understanding does not survive phase transitions.
Test names that describe functions instead of UX outcomes	"token refresh retries 3 times" tells nothing about UX. State what the user experiences.
Logs without a uxImpact field	Technical errors are invisible to UX triage. Always state the user-facing consequence.
Mixing a slug and a numeric ID as if they're interchangeable	Pick the slug as the one thing that travels through code/tests/commits; treat any numeric ID as optional metadata.

Related Skills

• intent-db — the local intent store this skill reads and writes (primary for feature/code-level intents).
• intent-alignment-audit — deeper, on-demand cross-reference of the intent store vs codebase @intent: tags.
• intent — the writing standard (/intent) required before composing any statement in this skill.
• Plan-writing and TDD skills, if you have them installed — this skill only covers the intent-linkage layer inside those disciplines, not their full mechanics.

Building a starting set instead of an empty store

A brand-new intent store has nothing in it. Rather than starting from zero one conversation at a time, mine your own past Claude Code sessions (~/.claude/projects/*/*.jsonl) for the trigger phrases in Phase 1's table — "users should never," "this is broken because…," and so on — and your project's own docs, and draft each match as a proposed entry (see intent-db) for you to confirm in batches. Nothing counts as settled until you approve it.