reverse-spec

name	reverse-spec
description	Reverse-engineer a spec from existing code — reconstructs presumed intent, event flow, external contracts, config, and business rules by reading source, tests, prompts, and git history. Use when inheriting undocumented behavior, onboarding onto a workflow agent or platform package, checking modern-pair drift, or capturing a baseline before a change or migration.

Reverse Spec

Read existing code and produce a filled-in spec as if the unit were being designed from scratch. The output is explicitly marked reverse-engineered and presumed — it reflects what the code does today, not necessarily what was intended.

Parameters: target (workflow agent, platform package, or specific component; optional port)

Usage examples:

/reverse-spec fixflow                      # workflow agent → add.spec.md-style output
/reverse-spec go/internal/ingest           # single package deep-dive
/reverse-spec reviewer python              # agent, specific port
/reverse-spec summary go python            # compare the modern pair for drift

When to Use

• Inheriting behavior — documentation is thin, you need the implicit contract
• Before a change or migration — reconstruct the "what" before changing the "how"; a baseline to verify equivalence after
• Onboarding — a structured document beats reading every file
• Validating the okf bundle — diff the reverse-spec against documentation to find drift
• Modern-pair drift check — reverse both Go and Python and compare (Go wins on undocumented disagreement, per okf/standards/language-parity.md)

Pre-flight: Subagent dispatch (multi-unit reverse-engineering)

When reverse-engineering more than one workflow agent, or one agent across both modern ports, dispatch one Explore agent BEFORE step 1 to map the surface in parallel — sequential reads of 20+ files compound otherwise:

Map the implementation of {target} in {port(s)} to seed a reverse-spec. Report:
- Every file path and 1-line purpose.
- Public surface (types, constructors, tool signatures).
- Env vars read and their defaults; webhook routes / check names touched.
- Prompt files used (prompts/ markdown).
- Test coverage breakdown and what the tests actually assert.
Output a structured summary, NOT raw code dumps.

For a single package (~10 files), direct reads are faster than briefing a subagent.

Information Sources

Read in order — each layer adds context the previous can't:

Source	What it reveals
okf/modules/agents/{name}.md (or platform/, ports/)	Documented intent (may be stale — note discrepancies)
okf/standards/architecture-design.md	Where this unit sits in the ingest→root→workflow path
Source (Go reference first: go/internal/, go/cmd/)	The actual public surface and logic
prompts/ markdown in the port	LLM instructions — the agent's real "business rules"
Config package + .env.example	Env vars, defaults, validation, precedence
Test files + fakes/stubs	What's actually enforced — the most reliable contract
The pair port (python/ for a Go target)	Parity or drift within the modern pair
git log --follow / git blame on the target dir	Who, when, why; recency of each section

Steps

1. Read the Code

For a workflow agent: bundle concept → agent wiring (build-agent pattern: pure wiring split from testable logic) → tools → prompts → platform packages it calls → tests and their fakes. For a platform package: its bundle concept → public surface → impl → tests.

2. Read Git History

git log --oneline --follow -- {target-dir}/      # evolution: who, when, why
git log --stat --follow -- {target-dir}/ | head -100   # decision points, refactors
git log --oneline -10 -- {target-dir}/           # actively maintained or dormant?

3. Produce the Reverse-Spec

Use the .agents/templates/add.spec.md structure (Context, Motivation, Scope, Design, Test plan, Rollout / rollback), populated from what the code actually does. Save as specs/<YYYYMMDD>-<slug>-reverse.md — specs/ is gitignored dev memory; never reference it from code, standards, or the okf bundle.

Critical — mark the entire output:

# ADD: {target} (reverse-engineered)

> Kind: add · Status: reverse-engineered {date} · Source commit: {short SHA}

> **This spec was reverse-engineered from the existing codebase.** It reflects what
> the code does today — not necessarily what was intended. Treat as presumed intent;
> verify before using as a source of truth. Generated by: /reverse-spec {target}

4. Fill in Each Section

• Context — what the unit is, where it sits in the ingest→root→workflow path, and which ports implement it (modern pair / frozen pair / all four)
• Motivation (presumed) — infer from prompts, commit messages, and the okf concept; flag anything that looks partially implemented or abandoned
• Scope — the observable behavior in vs out; note placeholder/stub paths
• Design — the load-bearing section:
  • Public surface: types, constructors, tool signatures, and their semantics
  • External contracts: webhook routes, check names, notify payloads, GitHub API calls, labels — cross-check okf/standards/webhooks.md; these bind all four ports
  • Config: every env var read, default, validation (cross-check .env.example)
  • Durable park/resume: does it suspend/resume? Resume keys, session usage (cross-check okf/orientation/suspend-resume-design.md)
  • Prompts: which prompts/ files, and the behavioral rules they encode
  • Pair parity: for a modern-pair target, note where Python matches or drifts from Go — per-item, with file paths on both sides
• Test plan (as found) — what's actually tested per layer; extract key scenarios as implicit acceptance criteria. The most reliable source of "what's enforced." Note coverage vs the ≥80% floor and any LLM-output assertions (a violation)
• Rollout / rollback (as found) — feature gating, deploy assumptions, kill switches

5. Flag Discrepancies

At the bottom of the spec:

## Discrepancies & Observations

### Code vs okf bundle
- [differences between documented intent and actual code — the code wins]

### Modern-pair drift
- [Go vs Python behavior differences not recorded as deliberate deltas]

### Incomplete Implementations
- [TODOs, placeholder data, dead branches]

### Missing Test Coverage
- [layers or scenarios with no tests]

### Potential Tech Debt
- [patterns that don't match the standards cited above]

### Questions for the Team
- [things code alone can't answer; intentional-looking logic with unclear why]

6. Grill Until Clean

A reverse-spec is built from inference, so it accumulates presumably / appears to / unclear why markers plus the Questions section. Follow the grill-me skill on the working spec with these marker targets:

• Every presumably / appears to / seems to qualifier
• Every entry under Questions for the Team
• Every Incomplete Implementation / Tech Debt item where intent is unclear
• Every modern-pair drift item: deliberate delta (record it) or a bug (spawn a fix)?

For each, present the codebase evidence, propose your best interpretation, and ask the user to confirm or correct. Write each resolution back immediately: replace presumably X with X when confirmed; rewrite the section when corrected; move unresolvables to ### Deferred with what would unblock them. Append a ## Decisions log above ## Discrepancies & Observations. The reverse-spec is not done while presumptions remain unconfirmed.

Output Format

A complete, grill-confirmed spec the user can: read (understand the unit fast), save (specs/<YYYYMMDD>-<slug>-reverse.md), feed forward (input to a change or migrate spec, no re-grilling), compare (diff against the okf concept to find documentation drift — fix the bundle, don't reference the spec), or share as a briefing.

Key Rules

• Report what IS, not what SHOULD BE — archaeology, not design
• Cite your sources — file paths (and line numbers) for every claim
• Flag uncertainty during inference, then grill it out — qualifiers are working state for steps 1–5; step 6 resolves every one (or defers with a logged reason)
• Don't skip tests — assertions are the most reliable truth
• Check git history for context — commit messages often explain "why"
• Note staleness — if the okf bundle contradicts the code, the code wins; list it under Discrepancies so the bundle gets fixed
• Go is the reference — for modern-pair targets, reverse Go first; Python drift is a finding, not a second source of truth
• No cross-language mentions leak into code — drift findings live in the spec, never as comments in a port

No Verification Needed

Read-only skill — produces a document, not code changes.