| 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}/
git log --stat --follow -- {target-dir}/ | head -100
git log --oneline -10 -- {target-dir}/
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.
