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

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

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

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

# 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.