stemedb/.claude/skills/aphoria-claims/SKILL.md

name	description
aphoria-claims	Author and review claims during diff review. Use when reviewing PRs, git diffs, or code changes to identify claimable decisions, suggest new claims, and check existing claims for violations. Triggers on "review diff for claims", "what claims does this change need", "aphoria claims review", "author claims for this diff".

Aphoria Claims Authoring Skill

You are an expert at identifying architectural decisions, safety invariants, and policy requirements hidden in code changes. Your job is to review diffs and help developers author proper claims with provenance, invariants, and consequences — not just observations.

The Key Distinction

	Observation	Claim
Source	Extractor (grep)	Human (deliberate)
Example	ordering = SeqCst at line 42	"All wallet atomics MUST use SeqCst"
Has	file, line, confidence	provenance, invariant, consequence, evidence
Stored	Ephemeral scan result	.aphoria/claims.toml (version-controlled)

Observations describe what IS. Claims describe what MUST BE and WHY.

Workflow: Reviewing a Diff for Claims

Step 1: Get the Diff

Read the git diff. If the user hasn't provided one:

git diff HEAD~1          # Last commit
git diff --staged        # Staged changes
git diff main...HEAD     # Branch changes

Step 2: Identify Claimable Patterns

Scan the diff for these categories:

Pattern in Diff	Category	Claim Signal
New constant or magic number	constants	Why this value? What breaks if changed?
New #[derive(...)] or removed derive	derives	Why these traits? Safety implications?
New import / removed import	imports	Dependency boundary? Why allowed/forbidden?
Atomic ordering choice	safety	Race condition implications?
Error handling strategy	architecture	Why this approach? What's the fallback?
Configuration default	constants	Why this default? What's the valid range?
Access control / auth check	safety	What's protected? What if bypassed?
Cryptographic choice	safety	Why this algorithm? Regulatory requirement?
New public API surface	architecture	Stability commitment? Breaking change policy?
Feature flag or toggle	architecture	Rollback plan? Who controls it?

Step 3: Check Existing Claims

Load the project's claims and check if the diff violates any:

aphoria claims list --format json

For each changed file, ask:

• Does this change contradict an existing claim's invariant?
• Does this change make an existing claim's consequence possible?
• Does this change supersede an existing claim?

Step 4: Draft Claims

For each claimable pattern found, draft using this template:

Thinking through the claim:

1. What must be true? (invariant) — The rule that must hold
2. Why? (provenance) — The analysis, decision, or spec that established this
3. What breaks? (consequence) — The concrete failure mode if violated
4. Says who? (authority tier) — How authoritative is this claim
5. Proof? (evidence) — ADRs, specs, safety analyses, benchmarks

Step 5: Create Claims via CLI

aphoria claims create \
  --id "<project>-<concept>-<seq>" \
  --concept-path "<project>/<module>/<concept>" \
  --predicate "<what_aspect>" \
  --value "<required_value>" \
  --provenance "<who/what established this>" \
  --invariant "<what MUST be true>" \
  --consequence "<what breaks if violated>" \
  --tier <regulatory|clinical|observational|expert|community|anecdotal> \
  --evidence "<reference>" \
  --category <safety|architecture|imports|constants|derives> \
  --by "<author>"

Authority Tier Guide

When helping users pick a tier, use this decision tree:

If the claim comes from...	Tier	Example
Law, regulation, compliance requirement	regulatory	"GDPR requires encryption at rest"
Published spec (RFC, OWASP, IEEE)	clinical	"RFC 7519 requires audience validation"
Benchmark data, load test results	observational	"Pool size >100 causes OOM under load"
Team lead / architect decision	expert	"All wallet atomics use SeqCst"
Convention, established pattern	community	"We use serde for serialization"
Individual opinion, preference	anecdotal	"I think 30s timeout is better"

Most project claims are expert (team decisions) or observational (measured).

Claim ID Convention

Format: <project>-<concept>-<sequence>

Examples:

• maxwell-seqcst-001 — Maxwell project, SeqCst ordering, first claim
• api-auth-jwt-001 — API project, JWT auth, first claim
• core-no-tokio-001 — Core crate, no-tokio rule, first claim

Keep IDs short, readable, and referenceable in commit messages.

Category Reference

Category	What It Covers	Typical Invariants
safety	Race conditions, memory safety, data integrity	"MUST use X ordering", "MUST NOT allow Y"
architecture	Module boundaries, dependency rules, API contracts	"Module X MUST NOT depend on Y"
imports	Allowed/forbidden dependencies	"Core MUST NOT import tokio"
constants	Magic numbers, configuration values	"Timeout MUST be >= 30s"
derives	Required/forbidden trait derivations	"Message types MUST derive Serialize"

Example: Full Diff Review

Given this diff:

+ const MAX_POOL_SIZE: u32 = 50;
+ const MIN_POOL_SIZE: u32 = 5;

Output:

## Claims Identified

### 1. Pool Size Bounds (constants)
The diff introduces pool size constants. These deserve claims because changing
them affects system stability under load.

**Suggested claims:**

aphoria claims create \
  --id "myapp-pool-max-001" \
  --concept-path "myapp/db/pool/max_size" \
  --predicate "max_value" \
  --value "50" \
  --provenance "Load testing showed OOM above 50 connections" \
  --invariant "Database pool size MUST NOT exceed 50" \
  --consequence "OOM kill under sustained load (>500 req/s)" \
  --tier observational \
  --evidence "Load test report 2026-01-15" \
  --category constants \
  --by jml

### 2. No Existing Claim Violations
Checked 3 existing claims — none are affected by this change.

Lifecycle Operations

When the diff supersedes or invalidates an existing claim:

# Update evidence on existing claim
aphoria claims update wallet-seqcst-001 \
  --evidence "New benchmark data from 2026-02"

# Supersede with new claim (old marked as superseded automatically)
aphoria claims supersede wallet-seqcst-001 \
  --new-id wallet-ordering-v2 \
  --value "Acquire" \
  --provenance "Updated safety analysis after AcqRel audit" \
  --by jml

# Deprecate if no longer relevant
aphoria claims deprecate old-claim-001 \
  --reason "Module removed in refactor"

Decision Points

Is This Worth a Claim?

Not every code change needs a claim. Ask:

Question	If Yes	If No
Would violating this break something?	Claim it	Skip
Would a new team member need to know this?	Claim it	Skip
Is there a non-obvious reason for this choice?	Claim it	Skip
Is this a temporary implementation detail?	Skip	—
Is this enforced by the type system already?	Skip	—

Claim vs Acknowledgment?

Situation	Use
"This MUST be true going forward"	aphoria claims create
"We know this conflicts but it's intentional"	aphoria ack add

Output Format

When reviewing a diff, produce:

## Claims Review for [diff description]

### New Claims Needed
1. **[claim-id]**: [invariant summary]
   - Category: [category]
   - Tier: [tier]
   - Rationale: [why this needs a claim]
   - Command: `aphoria claims create ...`

### Existing Claims Affected
1. **[claim-id]**: [what changed]
   - Action: Update / Supersede / Deprecate
   - Command: `aphoria claims [update|supersede|deprecate] ...`

### No Claim Needed
- [pattern]: [why it doesn't need a claim]

Constraints

1. Never invent provenance. If you don't know WHY a value was chosen, ask the developer.
2. Never guess consequences. If you can't articulate what breaks, don't claim it.
3. Prefer fewer, stronger claims over many weak ones. A claim without a real consequence is noise.
4. Match the project's existing claim style. Run aphoria claims list first to see conventions.
5. Always check existing claims first. Don't duplicate. Supersede if updating.

Related Skills

• aphoria-dev: Development guidelines for Aphoria
• aphoria-self-review: Evaluate scan quality and noise
• extract-claims: Extract claims from prose text (different from code diff review)