---
name: aphoria-claims
description: 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.

## Primary Workflow: Day-to-Day Claim Authoring (The Actual Use Case)

This is the real workflow — commit-time claim authoring driven by the skill calling CLI tools:

1. **Look at the entire diff** — Get the full context of what changed
2. **Identify claimable patterns** — Find things worth encoding as claims (spec constants, ordering, boundaries, derives on wire types)
3. **Look up existing claims** — Call `aphoria claims list` to check what already exists
4. **Align if needed** — If the diff changes something covered by a claim, use `aphoria claims update` or `supersede`
5. **Craft and submit new claims** — For new claimable patterns, draft claim with provenance/invariant/consequence, then call `aphoria claims create`
6. **Create extractors if needed** — For audit coverage, optionally create a paired extractor

**You drive the CLI.** You call `aphoria claims list|create|update|supersede` commands. The CLI doesn't know about you. You orchestrate the loop.

## Workflow: Reviewing a Diff for Claims

### Step 1: Get the Diff

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

```bash
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:

```bash
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

```bash
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:
```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:

```bash
# 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:

```markdown
## 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)