SuperAPI AI Directory

spec-retro

Coding & development

View repository

Updated 10-16 07:15

About this skill

Spec Retro

Mission

$spec-retro improves the specification system from observed practice.

It is separate from $spec-pipeline because it operates across:

  • multiple prior sessions;
  • multiple prior specs;
  • plans and execution outcomes;
  • governance receipts;
  • reports and telemetry;
  • exemplar libraries;
  • repeated failure patterns.

Its output is not a current implementation spec.

Its highest-value output is a small set of:

  • pipeline gate-rule updates;
  • challenge-rule updates;
  • fresh-eyes updates;
  • lint-rule updates;
  • mode-routing updates;
  • governance-receipt updates;
  • tool updates;
  • subagent-policy updates;
  • exemplar updates;
  • measurement updates.

Do not produce more process prose without an actionable rule or measurement.

Trigger policy

Use when any are true:

  • 5 or more full $spec-pipeline runs since the last retro;
  • 2 or more repeated gate/challenge/fresh-eyes/lint failures;
  • a report shows phase impact is invisible;
  • execution started before readiness;
  • plan or objective churn recurs;
  • no-grill justifications are repeatedly generic;
  • subagent fanout repeatedly has no impact;
  • strictness profiles are repeatedly mismatched;
  • current reports cannot distinguish pass-no-delta from route-changing phases.

Do not run after every spec.

Inputs

Use any available:

  • spec_governance_receipt / SGR-v2 records;
  • full spec outputs;
  • plan artifacts;
  • $grill-me snapshots;
  • execution outcomes;
  • $spec-pipeline reports;
  • session history;
  • seq results;
  • .learnings.jsonl;
  • user-supplied retrospective reports.

Evidence discipline

Separate:

retro_evidence:
  observed_pattern:
  supporting_sources: []
  counterevidence: []
  confidence:
  proposed_automation:
  expected_metric_change:

Do not infer a system-wide rule from one ambiguous session.

Churn detection

When given multiple plan/spec files, run:

python codex/skills/spec-retro/scripts/spec_churn_detect.py <files...>

The helper is heuristic. The model still judges whether churn is material.

Output

Emit one compact object:

spec_retro_update:
  update_version: SRETRO-v2
  report_window: "..."
  trigger:
    reason: "..."
    evidence_refs: []
  observed_patterns:
    - pattern: "..."
      confidence: high | medium | low
      counterevidence: []
  pipeline_updates:
    mode_routing: []
    gate_contract: []
    challenge_contract: []
    fresh_eyes_contract: []
    lint_contract: []
    governance_receipt: []
    output_templates: []
  tool_updates:
    spec_gate: []
    spec_lint: []
    sgr_gate: []
    churn_detector: []
  subagent_policy_updates: []
  exemplar_updates: []
  measurement_updates:
    - metric: "..."
      baseline: "..."
      expected_change: "..."
      next_report_query: "..."
  recommendations:
    keep: []
    revise: []
    retire: []
  apply_now: yes | no
  next_owner: spec-pipeline | spec-retro | tune | seq | user | none

Decision standard

A proposed change is useful only if it can later be graded.

Every recommendation must specify:

hypothesis
expected behavioral change
metric
next report query
keep/revise/retire condition

Subagent use

Preferred historical worker:

spec_retro_miner

Use it only when evidence spans enough artifacts to benefit from a separate historical pass.

The root owns synthesis and recommendation.

Guardrails

  • Do not create a current implementation spec.
  • Do not lint or challenge one current spec as the primary task.
  • Do not mutate skill files unless explicitly asked.
  • Do not chase old standalone companion-skill activation counts.
  • Do not turn phase pass-no-delta into success theatre.
  • Do not propose a process rule with no future measurement.
  • Do not run as per-spec ceremony.

Resources