spec-audit

name	spec-audit
description	Audit specs for format compliance, concept fragmentation, tree hygiene, and evidence quality. Use when reviewing spec quality, consolidating fragmented specs, cleaning up tree structure, or batch-migrating specs from old formats.

Spec Audit

Overview

Systematically audit specs in the Mighty graph for format compliance, hierarchy semantics, and evidence placement, then migrate non-conforming specs to the canonical Guarantees + Constraints structure.

When to use

• After adopting the new spec format and needing to migrate existing specs.
• Periodic hygiene: find specs with missing sections, stale prose, or structural issues.
• Before a major planning push: ensure the spec tree is clean and navigable.
• Before implementation: verify a leaf spec is semantically ready (semantic audit mode).

Audit modes

This skill has two modes. Use the right one for the goal:

• Format audit: checks structural compliance — headings, bullets, tree shape, citation format, evidence placement. Cheap, run often.
• Semantic audit: checks whether a spec is ready for implementation — failure modes covered, external boundaries defined, verification paths clear, evidence edges specific enough for semantic coverage. More expensive, run before task creation on leaf specs.

Format audit workflow

1) Scan the tree

mt tree --all

Walk each root and its children. For every spec, run mt show <id> and check against the format checklist (references/format-checklist.md).

2) Identify non-conforming specs

Flag specs that have any of the red flags in references/format-checklist.md. Key categories:

Format issues:

• ## Behaviors or ## Interfaces sections (old format)
• Missing ## Guarantees or ## Constraints section
• Unstructured prose instead of bullet lists
• Product spec using Guarantees/Constraints instead of Problem/Goal/Approach/Success

Concept fragmentation:

• Two or more specs implemented_by the same source file (likely one concept split into multiple specs — merge them)
• Child spec exists because a design question was answered iteratively, not because it's a distinct concept (fold back into parent)
• Multiple specs describing different "angles" of the same mechanism (merge into one spec for that mechanism)

Tree structure:

• Parent spec is just an index listing children with no guarantees, constraints, or product framing
• CLI command spec placed outside the CLI tree
• Test artifact or temporary probe in the spec tree (tombstone it)
• Completed evaluation ("should we use X?") as a spec (should be a decision)
• Spec marked Active with no implemented_by evidence pointing to code (should be Draft)
• Nesting deeper than 3 levels

Evidence:

• Generic evidence descriptions like Core implementation or Coverage
• Evidence on an umbrella parent when a more specific live child owns the behavior

3) Migrate specs

Use mt show --json <id> | jq -r '.description' to get the current description and mt show <id> --sections to enumerate sections, then transform section by section following the migration patterns (references/migration-patterns.md).

Apply with mt edit section by section (preferred — preserves comment anchors and CRDT identity):

# For each section that needs migration:
mt show <id> --section @s:N > /tmp/section.yaml
# ...transform the YAML in place (rename headings, rewrap bullets, etc.)...
mt edit <id> --section @s:N --content-file /tmp/section.yaml

Only if the spec has no user comments and you must rewrite it from scratch (last resort):

cat <<'EOF' | mt update <id> --description-file -
<new description>
EOF

Migrating with mt update --description-file destroys all comment anchors, citation instance IDs, and CRDT node identity. Prefer mt edit unless the spec is a fresh unpublished draft.

4) Validate tree structure

After migration, verify:

• Max 3 levels deep (root → mid → leaf)
• Every non-root spec has a parent via child_of edge
• Root specs are area/capability buckets, not implementation details
• Parent summaries still accurately describe their children
• Each child_of edge description explains how the child refines a specific parent guarantee or constraint
• Evidence descriptions name the exact guarantee or constraint they cover
• Evidence lives on the most specific active spec that owns the behavior
• Reading the parent summary, children, and edge descriptions gives a coherent picture of current intent and coverage

5) Batch workflow

Process in tree order — roots first, then children:

1. Migrate root/parent specs first (they set the framing for children)
2. Migrate children, checking consistency with parent
3. After migrating children, re-read parent to update its summary if children changed scope
4. Tighten child_of and evidence descriptions so the subtree reads semantically, not just structurally
5. Leave a comment on each migrated spec: mt comment --on <id> --content "Migrated to Guarantees + Constraints + semantic edge format"

Spec retirement workflow

Use this workflow when deprecating, merging, or tombstoning specs during audits and consolidation.

When to use each state

• Deprecated: The spec described something real but it's been superseded. The replacement exists. Use when merging specs (the absorbed spec becomes Deprecated) or when a feature is replaced by a different approach. Deprecated specs stay visible in the graph for historical context.
• Tombstone (via mt delete): The spec should not have existed or is no longer relevant at all. Test artifacts, duplicates, completed evaluations that should have been decisions, temporary probes. Tombstoned specs are hidden from mt tree and queries.

Retirement checklist

Before retiring a spec:

1. Reparent children. If the spec has Active children, move them first:

   • Find a suitable new parent and mt link --from <child> --rel child_of --to-spec <new-parent> -d "..."
   • Or promote them to roots if no parent fits
   • Never tombstone a parent without handling its children — they become orphans

2. Move evidence. If the spec has implemented_by or tested_by edges pointing to code that is still relevant:

   • Relink evidence to the spec that now owns that contract (the merge target or the new parent)
   • Don't leave evidence dangling on a deprecated spec when an active spec covers the same code

3. Record the reason. Always use --reason so the history is traceable:

   • Deprecate: mt update <id> --status deprecated --reason "Merged into <target-id>; guarantees absorbed"
   • Tombstone: mt delete <id> --reason "Test artifact, not a real spec"

4. Comment on the merge target. When merging specs, leave a comment on the surviving spec noting what was absorbed:

   • mt comment --on <target-id> --content "Absorbed guarantees from [Retired spec](cite:<retired-id>): <brief description of what was added>"

Merging specs (consolidation)

When two or more specs describe the same concept and should become one:

1. Choose the merge target — the spec with the best title, most evidence, and clearest framing. Prefer Active over Draft.
2. Read all specs being merged. Combine their guarantees and constraints into the target, deduplicating and resolving any conflicts.
3. Move evidence edges from the absorbed specs to the target.
4. Reparent any children of the absorbed specs.
5. Deprecate the absorbed specs with a reason citing the merge target.
6. Comment on the target noting what was absorbed.

Batch retirement

When retiring many specs (e.g., during a tree audit), process in this order:

1. Tombstone test artifacts and duplicates first (no children, no evidence to move)
2. Merge fragmented specs next (move evidence and guarantees to targets)
3. Deprecate empty containers last (after their children have been reparented)
4. Run mt tree after each batch to verify no orphans were created

Semantic audit workflow

Use semantic audit on leaf specs before task creation, or when reviewing whether a spec is implementation-ready.

1) Check implementation-readiness conditions

For each leaf spec, verify:

• No [blocking] open questions remain
• All affecting decision candidates are resolved
• Strict pressure-test lenses pass (see below)
• Evidence edge descriptions are specific enough to map to individual guarantees/constraints (not generic labels like "Core implementation")

2) Run pressure-test lenses

Walk each lens in order. Stop early if lenses 1–4 come back clean:

1. Failure / recovery (scoped to operations, async flows, external boundaries, state transitions — not required for invariants or static properties): For each guarantee in these categories, is the failure mode specified?
2. External boundaries: Where does this spec interact with systems or actors outside its control? Are interface contracts defined?
3. State / data invariants: What must always be true? Are there race conditions or partial-update scenarios?
4. Objectives / budgets: Are there latency, size, cost, or resource constraints that would cause two implementations to diverge?
5. Inputs / events: Are edge-case inputs defined (empty, maximum, malformed, concurrent)?
6. Verification: How would you prove each guarantee holds? Is there a verification strategy for non-obvious claims?
7. Actor / outcome: Are actor expectations unambiguous?
8. Explicit freedoms: Are there decisions that look like freedom but actually matter?

At most one question per lens. If a gap changes user-visible behavior or non-negotiables → flag as blocking. If it only affects internal shape → note as discretion.

3) Produce a gap report

For each lens, classify findings:

• Resolved: already covered by the spec
• Ambiguous: admits multiple valid implementations where the user would care which → update spec or record decision
• Assumed: implicit assumption the spec relies on but doesn't state → add as constraint or link to sibling spec
• Free: explicitly left to implementation discretion

4) Check cross-spec interactions

• Are there ordering dependencies, shared state, or conflicting constraints with sibling or parent specs?
• Are parent clauses that should propagate to this leaf explicitly marked as cross-cutting?

Reference files

• Format compliance checklist: references/format-checklist.md
• Old → new migration patterns: references/migration-patterns.md
• Canonical spec template: see .agents/skills/mighty/planning/references/spec-template.md
• Spec examples by domain: see .agents/skills/mighty/planning/references/examples.md