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

---
name: aphoria-suggest
description: Suggest new claims by analyzing existing patterns and unclaimed observations. Use when you want to grow claim coverage, find unclaimed code patterns, or bootstrap claims for a new project. Triggers on "suggest claims", "what needs claims", "aphoria suggest", "grow coverage", "bootstrap claims".
---

# Aphoria Claim Suggester

You are an expert at identifying **semantic patterns** across authored claims and recognizing analogous unclaimed observations that deserve claims. You use the Aphoria CLI as your data source and your reasoning as the intelligence layer.

## Core Principle: Skill Calls CLI

You do NOT train models or use embeddings. You:
1. Call the CLI to get structured data (claims + observations)
2. Reason over the data to find patterns
3. Suggest new claims with ready-to-run CLI commands

The "learning" is your ability to read existing claims, understand their semantic patterns, and apply that understanding to unclaimed observations.

## Workflow

### Phase 1: Gather Context

Run these commands to understand the project's current claim state:

```bash
# Get all authored claims (the "gold standard" examples)
aphoria claims list --format json

# Get verification results including unclaimed observations
aphoria verify run --format json --show-unclaimed

# Get coverage gaps
aphoria coverage --format json
```

### Phase 2: Determine Mode

Based on the claim count, choose your approach:

| Claim Count | Mode | Strategy |
|---|---|---|
| 0 | **Cold Start** | Bootstrap from project docs, tests, and conventions |
| 1-5 | **Foundation** | Extend existing patterns, fill obvious gaps |
| 6+ | **Flywheel** | Full analogical reasoning from established patterns |

### Phase 3a: Cold Start (0 Claims)

When no claims exist, bootstrap from external context:

1. **Read architecture docs**: `CLAUDE.md`, `README.md`, `docs/adr/`, `.claude/`
2. **Inspect tests for implicit invariants**: Property-based tests, assertion patterns, `#[should_panic]` tests
3. **Identify tech stack conventions**: What framework? What serialization? What auth pattern?
4. **Propose 3-5 foundation claims** in these categories:
   - **Safety**: Race conditions, data integrity, resource management
   - **Architecture**: Module boundaries, dependency rules
   - **Constants**: Magic numbers from specs, configuration bounds

Example cold start output:
```
## Bootstrap Claims Suggested

No existing claims found. Here are foundation claims based on project analysis:

### 1. [safety] Serialization Consistency
Reading tests in `tests/serialization.rs` — there's a roundtrip property test.

**Invariant:** All persistent types MUST implement roundtrip serialization
**Consequence:** Data corruption on disk or wire
**Evidence:** Property test at tests/serialization.rs:42

aphoria claims create \
  --id "project-serde-roundtrip-001" \
  --concept-path "project/types/serialization" \
  --predicate "roundtrip_safe" \
  --value "true" \
  --provenance "Property-based test coverage" \
  --invariant "All persistent types MUST serialize/deserialize without data loss" \
  --consequence "Data corruption in WAL or network protocol" \
  --tier expert \
  --evidence "tests/serialization.rs:42" \
  --category safety \
  --by "aphoria-suggest"
```

### Phase 3b: Foundation Mode (1-5 Claims)

With a few claims, extend the patterns:

1. **Identify the categories covered** — What has claims? Safety? Architecture?
2. **Find gaps in the same categories** — If there's a SeqCst claim for wallet, check other atomic code
3. **Suggest 2-3 claims** that extend existing patterns to new locations

### Phase 3c: Flywheel Mode (6+ Claims)

Full analogical reasoning:

1. **Group existing claims by semantic pattern** (not string matching):
   - "Ordering invariants" (SeqCst claims across modules)
   - "Boundary rules" (no-import claims for module isolation)
   - "Serialization requirements" (derive claims for wire types)
   - "Configuration bounds" (min/max value claims)

2. **For each unclaimed observation**, apply chain-of-thought:
   ```
   THINKING:
   - Observation: `Ordering::Relaxed` at sync/coordinator.rs:87
   - Most similar claim: wallet-seqcst-001 ("All wallet atomics MUST use SeqCst")
   - Similarity: Both involve atomic ordering in critical data paths
   - Difference: Coordinator vs wallet — is coordinator also safety-critical?
   - Decision: YES — coordinator manages distributed state, weakened ordering
     could cause split-brain. SUGGEST a claim.
   ```

3. **Rank suggestions by coverage impact**:
   - Modules with 0 claims but many observations = highest priority
   - Patterns that appear in 3+ locations = systematic invariant
   - Safety-category gaps > architecture > constants

### Phase 4: Output Suggestions

For each suggestion, produce:

```markdown
## Suggestion N: [Short Title]

**Reasoning:** [Chain-of-thought explanation]
**Analogous to:** [existing claim ID, if any]
**Coverage impact:** [module name] goes from X% to Y% claimed

aphoria claims create \
  --id "<suggested-id>" \
  --concept-path "<path>" \
  --predicate "<predicate>" \
  --value "<value>" \
  --provenance "<source>" \
  --invariant "<what MUST be true>" \
  --consequence "<what breaks>" \
  --tier <tier> \
  --evidence "<reference>" \
  --category <category> \
  --by "<author>"
```

## Context Management

To avoid context window saturation with large projects:

| Situation | Strategy |
|---|---|
| <50 claims, <200 observations | Load everything, reason holistically |
| 50-200 claims | Filter by `--category` relevant to current work |
| 200+ claims | Use coverage gaps to focus on highest-impact modules only |
| 1000+ observations | Use `aphoria coverage --sort-by unclaimed` to prioritize |

When filtering:
```bash
# Focus on safety claims only
aphoria claims list --format json --category safety

# Focus on a specific module
aphoria verify run --format json --show-unclaimed --path src/wallet/
```

## Quality Gates

Before suggesting a claim, verify it passes these checks:

| Check | Requirement |
|---|---|
| **Non-trivial** | Would violating this actually break something? |
| **Not type-system enforced** | The compiler doesn't already catch this |
| **Has a consequence** | You can articulate a specific failure mode |
| **Has provenance** | You can point to WHY this must be true |
| **Not a duplicate** | No existing claim covers this |
| **Testable** | An extractor can verify this observation |

## Anti-Patterns

**Do NOT suggest claims for:**
- Variable renames, whitespace changes, comment additions
- Patterns enforced by the type system or compiler
- Temporary implementation details ("TODO: refactor this")
- Generic boilerplate ("all functions should have docs")
- Observations where the value can never realistically change

**Do NOT generate:**
- Template garbage invariants ("This value MUST be what it is")
- Claims without specific consequences ("Bad things could happen")
- Claims with invented provenance ("Industry best practice")

## Integration with Existing Skills

This skill complements:
- **aphoria-claims**: Reviews diffs for claimable changes (reactive — triggered by code changes)
- **aphoria-suggest**: Proactively scans for coverage gaps (proactive — triggered by developer request)
- **aphoria-self-review**: Evaluates scan quality and noise

Typical workflow:
1. `aphoria-suggest` identifies systematic gaps → developer authors claims
2. `aphoria-claims` catches new claimable patterns in future diffs
3. More claims → better suggestions → flywheel spins

## Example Session

```
User: "suggest claims for this project"

Agent:
1. Runs `aphoria claims list --format json` → 4 claims (all safety category)
2. Runs `aphoria verify run --format json --show-unclaimed` → 23 unclaimed observations
3. Runs `aphoria coverage --format json` → 3 modules with 0 claims
4. Identifies: existing claims all about atomic ordering
5. Finds: 5 unclaimed observations also involve Ordering:: in different modules
6. Suggests: 3 new SeqCst claims for uncovered modules + 2 architecture boundary claims
7. Outputs: ready-to-run aphoria claims create commands with reasoning
```

## Constraints

1. **Never invent provenance.** If you don't know WHY, mark the tier as `community` and note "needs expert review."
2. **Never suggest more than 10 claims at once.** Prioritize by impact.
3. **Always show reasoning.** The developer should understand WHY you're suggesting each claim.
4. **Match existing style.** If project claims use formal MUST/SHALL language, match it.
5. **Prefer fewer strong claims** over many weak ones.
6. **Run coverage after suggesting.** Show the before/after impact.