reverse-spec
Skill4 starsChanged 5 months agoMITView on GitHub
Reverse-engineer an existing codebase into an extremely detailed SPEC.md that is sufficient for another agent to rebuild a closely matching working application. Use when the user asks to generate a full spec, PRD, architecture blueprint, implementation plan, acceptance criteria, edge cases, design/writing style guide, or a reconstruction-ready technical specification from existing code.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-friendly-tuiSkill
- copilot-sdk-nodejsSkill
- image-genSkill
- impactful-titlesSkill
- public-tunnelSkill
- readmeSkill
- telegram-sendSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Always create or update a single file named SPEC.md at the repository root.
- Very specific: line 24
If information is unknown, do not invent details.
- Distinctive: line 40
Use code search and tests aggressively.
- Distinctive: line 54
Prefer behavioral statements over implementation trivia.
- Very specific: line 78
Before finalizing SPEC.md, run a gap check:
- Distinctive: line 85
If not, expand the missing sections.
- Distinctive: line 89
Use this exact top-level structure:
- Very specific: line 110
Do not omit sections. Use Unknown where necessary.
- Distinctive: line 202
If UI exists, define:
- Distinctive: line 210
If textual outputs exist, define:
- Distinctive: line 255
When detail is uncertain, include:
- Distinctive: line 263
Do not expose secrets or credentials.
- Distinctive: line 264
Do not include irrelevant implementation noise.
- Distinctive: line 265
Do not claim parity if key behavior is undocumented.
- Distinctive: line 266
Do not stop at architecture summary.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Reverse Spec
Produce a reconstruction-grade SPEC.md from an existing codebase.
Primary objective: create a specification detailed enough that another agent can rebuild a functionally equivalent application with minimal guesswork.
Output Contract
Always create or update a single file named SPEC.md at the repository root.
The output must be:
- Evidence-based: derive claims from source code, tests, config, docs, scripts, and observed runtime behavior.
- Reconstruction-oriented: specify what to build, how it behaves, and how to verify parity.
- Testable: include explicit checks and acceptance criteria.
- Complete: cover product, architecture, data, workflows, edge cases, style, and operations.
If information is unknown, do not invent details. Mark clearly as Unknown with a concrete plan to verify.
Execution Workflow
1. Scope and Inventory
Build a complete inventory of the system:
- Entry points and startup flow
- Major modules and boundaries
- User-visible capabilities
- Storage, state, and data flow
- Integrations and external dependencies
- Build/test/release/deploy commands
- Configuration and environment variables
Use code search and tests aggressively. Tests often encode behavior not documented elsewhere.
2. Behavioral Extraction
For each feature, document:
- Trigger/input
- Preconditions
- Main flow
- Alternate flows
- Error flows
- Side effects
- Observable outputs
Prefer behavioral statements over implementation trivia.
3. Architecture and Contracts
Extract explicit contracts:
- Module responsibilities
- Public interfaces and function contracts
- Message/event schemas
- API request/response shapes
- Persistence schemas and invariants
- Cross-module call flows
4. Reconstruction Blueprint
Translate findings into build instructions:
- Ordered implementation phases
- Dependency graph between components
- Minimal viable scaffold then parity increments
- Validation gates per phase
5. Completeness Review
Before finalizing SPEC.md, run a gap check:
- Can a new agent rebuild without opening the original code?
- Are all critical workflows specified end-to-end?
- Are acceptance checks explicit and executable?
- Are edge cases and failure modes covered?
If not, expand the missing sections.
Required SPEC.md Structure
Use this exact top-level structure:
# Product Specification## 1. Purpose and Scope## 2. Product Definition (PRD)## 3. Users, Actors, and Use Cases## 4. Functional Requirements## 5. Non-Functional Requirements## 6. System Architecture## 7. Data Model and State## 8. Interfaces and Integrations## 9. Core Workflows## 10. Edge Cases and Failure Handling## 11. Security, Privacy, and Safety## 12. UX, Content, and Writing Style## 13. Build, Run, and Operations## 14. Testing and Verification## 15. Reimplementation Plan## 16. Traceability Matrix## 17. Open Questions and Unknowns
Do not omit sections. Use Unknown where necessary.
Section Rules
2. Product Definition (PRD)
Include:
- Problem statement
- Goals and non-goals
- Success metrics
- Constraints
- Release boundaries (must-have vs nice-to-have)
4. Functional Requirements
List requirements as IDs: FR-001, FR-002, etc.
Each FR-* must include:
- Requirement statement
- Rationale
- Inputs and outputs
- Preconditions
- Postconditions
- Deterministic acceptance checks
5. Non-Functional Requirements
List as NFR-* with measurable targets where possible:
- Performance
- Reliability
- Maintainability
- Observability
- Accessibility (if UI)
- Portability
6. System Architecture
Provide:
- Component map with responsibilities
- Runtime topology
- Startup and shutdown sequences
- Data and control flow
- Key design decisions and trade-offs
7. Data Model and State
Document:
- Persistent entities and fields
- Relationships
- Constraints and invariants
- State machines and status transitions
- Migration/versioning concerns
8. Interfaces and Integrations
For each interface:
- Protocol/transport
- Request and response schema
- Error schema
- Retry/idempotency behavior
- Authentication/authorization model
- Timeouts and rate limits
9. Core Workflows
Describe each workflow as:
- Trigger
- Step-by-step sequence
- Decision points
- Failure branches
- Completion criteria
10. Edge Cases and Failure Handling
Catalog failure modes with mitigation:
- Invalid input
- Missing dependencies
- Network or service outages
- Data corruption or partial failure
- Concurrency races
- Recovery behavior
12. UX, Content, and Writing Style
If UI exists, define:
- Information architecture
- Navigation and layout behavior
- Visual system tokens (color, typography, spacing)
- Interaction and feedback states
- Empty/loading/error states
If textual outputs exist, define:
- Voice and tone
- Message structure
- Formatting conventions
- Forbidden wording/patterns
14. Testing and Verification
Define a parity test plan:
- Unit, integration, and end-to-end checks
- Golden-path scenarios
- Regression suite
- Deterministic pass/fail criteria
- Manual verification checklist for hard-to-automate behavior
15. Reimplementation Plan
Provide an ordered build plan with milestones:
- Phase goal
- Deliverables
- Dependencies
- Validation checks
- Exit criteria
16. Traceability Matrix
Map each requirement to evidence and tests:
- Requirement ID
- Source evidence (files/tests/docs)
- Verification method
- Risk if incorrect
Quality Bar
SPEC.md must be:
- Specific over generic
- Declarative over ambiguous
- Verifiable over descriptive
- Complete enough to drive implementation without code access
When detail is uncertain, include:
AssumptionRiskHow to verify
Guardrails
- Do not expose secrets or credentials.
- Do not include irrelevant implementation noise.
- Do not claim parity if key behavior is undocumented.
- Do not stop at architecture summary; include concrete behavior and checks.
Done Criteria
The skill is complete only when SPEC.md enables another agent to:
- Recreate core architecture and module boundaries.
- Reproduce all primary workflows and failure behaviors.
- Implement interfaces and data model with matching constraints.
- Validate parity through explicit tests/checklists included in the spec.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

