derive-spec
Derive Spec
Given an existing codebase, produce a single Markdown specification that a separate team could rebuild from — in the same stack or a different one — without consulting the original code. The document is a hybrid Software Requirements Specification (loosely IEEE 830 / ISO/IEC/IEEE 29148:2018) and Product Requirements Document: product framing on top, functional and non-functional requirements with stable IDs in the middle, technical architecture and business rules at the bottom, open questions consolidated at the end.
The document is a frozen snapshot of the application at the moment the skill runs. It describes what currently exists; it does not track what was, what's planned, or what was deprecated. A later run on the same codebase produces a fresh, independent snapshot.
The skill's value is coverage and traceability, not stylistic polish. Bugs of omission in the spec become bugs in the rebuild. Bias toward completeness over speed; this skill is expected to be slow.
What this skill is — and isn't
- Do: read the source, infer what the app currently does, write the spec, flag what cannot be determined from code as Open Questions.
- Don't: write any code, edit any file outside the spec output path, refactor "while we're here", or run anything destructive. This skill is read-only with respect to the source codebase.
- Stack-agnostic on both sides: never mention or assume the source technology (framework, language, build system) or any target rebuild technology. The document describes what the app does, not how to port it.
- No migration content: never include sections titled "Migration Notes", "Implementation Hints", "Rebuild Considerations", "Source → Target Mapping", or any equivalent. That ground is explicitly out of scope. A source→target mapping would lock the document to one rebuild target and shorten its useful life — let the rebuild project produce its own mapping doc separately.
- No history, no deprecation: the spec is a snapshot of the present. No "previously did X" notes, no
[DEPRECATED]markers, no change logs versus a prior run. If a feature isn't in the code right now, it isn't in the spec. - Single file: always one Markdown file. No master index, no per-area splits, no companion files.
- Honest about fidelity: a "1:1 rebuild" is bounded by what's observable in the code plus what humans answer in the Open Questions section. Say so in the methodology preamble; never paper over it.