agentleFS
sinediedsinedied/agent-skills/.agents/skills/reverse-spec/SKILL.md

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.

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
  1. Very specific:

    Always create or update a single file named SPEC.md at the repository root.

    line 15
  2. Very specific:

    If information is unknown, do not invent details.

    line 24
  3. Distinctive:

    Use code search and tests aggressively.

    line 40
  4. Distinctive:

    Prefer behavioral statements over implementation trivia.

    line 54
  5. Very specific:

    Before finalizing SPEC.md, run a gap check:

    line 78
  6. Distinctive:

    If not, expand the missing sections.

    line 85
  7. Distinctive:

    Use this exact top-level structure:

    line 89
  8. Very specific:

    Do not omit sections. Use Unknown where necessary.

    line 110
  9. Distinctive:

    If UI exists, define:

    line 202
  10. Distinctive:

    If textual outputs exist, define:

    line 210
  11. Distinctive:

    When detail is uncertain, include:

    line 255
  12. Distinctive:

    Do not expose secrets or credentials.

    line 263
  13. Distinctive:

    Do not include irrelevant implementation noise.

    line 264
  14. Distinctive:

    Do not claim parity if key behavior is undocumented.

    line 265
  15. Distinctive:

    Do not stop at architecture summary.

    line 266

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Evidence-based: derive claims from source code, tests, config, docs, scripts, and observed runtime behavior.
  2. Reconstruction-oriented: specify what to build, how it behaves, and how to verify parity.
  3. Testable: include explicit checks and acceptance criteria.
  4. 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:

  1. # Product Specification
  2. ## 1. Purpose and Scope
  3. ## 2. Product Definition (PRD)
  4. ## 3. Users, Actors, and Use Cases
  5. ## 4. Functional Requirements
  6. ## 5. Non-Functional Requirements
  7. ## 6. System Architecture
  8. ## 7. Data Model and State
  9. ## 8. Interfaces and Integrations
  10. ## 9. Core Workflows
  11. ## 10. Edge Cases and Failure Handling
  12. ## 11. Security, Privacy, and Safety
  13. ## 12. UX, Content, and Writing Style
  14. ## 13. Build, Run, and Operations
  15. ## 14. Testing and Verification
  16. ## 15. Reimplementation Plan
  17. ## 16. Traceability Matrix
  18. ## 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:

  • Assumption
  • Risk
  • How 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:

  1. Recreate core architecture and module boundaries.
  2. Reproduce all primary workflows and failure behaviors.
  3. Implement interfaces and data model with matching constraints.
  4. Validate parity through explicit tests/checklists included in the spec.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.