axiom-miner

Axiom Miner

A frontier-model agent invoking this skill should:

1. Read the heuristics data file at heuristics.json — the seven categories of unspoken knowledge and example questions per category.
2. Read the project's knowledge base (path injected by orchestrator) — what's already documented.
3. Read the task neighborhood — only files mentioned by the task and their immediate imports (5-15 files max).
4. Gap analysis — compare patterns observed in code against what's documented. Anything in code but not in docs is an axiom candidate.
5. Generate questions — across the seven categories, prioritized by task-relevance and consequence.

When to invoke

Auto-fires when the task description lacks structural markers (no acceptance criteria, no repro steps, no expected vs actual sections) and is short (< 500 chars). Configured via specialized_agents.axiom_miner.triggers in workflow-config.yaml.

Skip when:

• Task has a linked beads issue with clear acceptance criteria
• Task description includes explicit constraints + scope
• Planner's first pass produces high-confidence output without gap signals

Output

{
  "questions": [
    {
      "priority": "critical|important|nice_to_know",
      "category": "data_semantics|lifecycle|history|deployment|business|conventions|integration",
      "question": "<the question>",
      "best_guess": "<what the code suggests>",
      "evidence": "<files/patterns observed>"
    }
  ],
  "axioms_confirmed": [
    {"statement": "...", "evidence": "..."}
  ]
}

The full prompt with the seven-category framework lives at agents/axiom-miner.md. This skill descriptor is the contract for invoking it via Claude Code Skills; the data canonical source is heuristics.json.