reverse-spec-from-repo

name	reverse-spec-from-repo
description	Use when analyzing an existing repository to reconstruct missing or outdated agent-facing prompt specs from code, tests, docs, and configuration, especially before planning, onboarding, repo handoff, or coding-agent execution.

Reverse Spec From Repo

Reverse-engineer a usable prompt-spec suite from an existing codebase. Focus on producing a traceable set of prompts that a human can hand to a coding agent. Keep observed behavior, inferred intent, and unresolved ambiguity separate — this is not a file-by-file summary.

When To Use

Use this skill when:

• the repo contains code but no trustworthy spec
• the current spec is stale and implementation reflects the real source of truth
• you need to understand a codebase before planning new work
• you want to ground future agents on prompt specs instead of raw code archaeology
• the user asks to reverse-engineer specs (e.g., 反推 spec or 从仓库生成 规格)
• the user wants a repo-to-prompt handoff for vibe coding

Do not use this skill when:

• the user already provided a current approved spec and just wants implementation
• the task is a small bugfix that only needs local code reading
• you are doing architecture review without needing a formal spec artifact

Core Rules

• Evidence before interpretation. Every important statement in the prompt suite must be backed by repo evidence or marked as an inference.
• Never present inferred intent as established fact.
• Prefer bounded scope over fake completeness. For large repos, narrow the target first.
• Output files, not chat-only summaries.
• The deliverable is a prompt-spec package under spec/, not a code walkthrough.
• Write prompts for a capable coding agent: be outcome-first, constraint-aware, and explicit about what must be preserved.
• Be clear about what the agent may decide.
• Do not write fluffy “vibe” prose. Vibe coding here means high-bandwidth human intent transfer, not vague inspiration.

Required Output

Create a run directory:

spec/<YYYY-MM-DD>-<scope>-reverse-spec/

Write at least these files:

• README.md
• context-manifest.md
• evidence.md
• prompts/00-repo-brief.md
• prompts/01-system-spec.md
• prompts/modules/<module>.md
• prompts/workflows/<workflow>.md

Use references/spec-template.md for the prompt-suite structure. Use references/evidence-checklist.md for evidence logging and QA.

Workflow

0. Scope The Analysis

Decide whether this work is a whole-repo reverse spec, a subsystem reverse spec, or a feature-path reverse spec. If the repo is too large for one pass, explicitly narrow scope by service, package, executable, or user flow. Do not pretend to cover the full repo when you only inspected one slice.

1. Initialize The Spec Run

Create spec/<YYYY-MM-DD>-<scope>-reverse-spec/. Start context-manifest.md immediately. Record:

• the task
• loaded context
• excluded context
• key decisions
• risks

This is mandatory. Reverse-engineering a spec without a context boundary produces low-trust output.

2. Read The Highest-Signal Surfaces First

Start from the surfaces most likely to encode intended behavior:

1. README*, docs/, and onboarding docs
2. language/runtime manifests such as go.mod, package.json, Cargo.toml, pyproject.toml
3. entrypoints like main.*, cmd/, src/index.*, and service bootstrap files
4. configuration schemas and environment wiring
5. tests, especially integration and end-to-end suites
6. public interfaces such as API specs, routes, CLI commands, queue topics, and DB schema migrations

Only then descend into implementation details.

3. Build An Evidence Ledger

For every meaningful claim, capture:

• claim ID
• statement
• evidence type
• file path and line reference
• confidence level
• whether the claim is observed, inferred, or unresolved

Store this ledger in evidence.md.

Good evidence sources:

• tests proving behavior
• interface definitions
• config defaults
• schema and migrations
• comments or ADRs with clear intent
• docs that still match code

Weaker evidence sources:

• stale comments
• TODOs
• naming alone
• one-off code paths without tests

4. Reconstruct The Prompt-Spec Suite

Write the prompt suite from the template. Focus on:

• system purpose
• actors and stakeholders
• major capabilities
• key workflows
• interfaces and dependencies
• domain concepts and invariants
• operational and non-functional constraints
• failure modes and safety boundaries
• explicit non-goals when you can infer them with confidence

Do not turn the suite into a directory listing.

The output should be layered:

• 00-repo-brief.md (short handoff prompt, top-of-mind context, and urgent constraints)
• 01-system-spec.md (system-level prompt describing goals, invariants, interfaces, and acceptance criteria)
• modules/<module>.md (one prompt per important module or subsystem)
• workflows/<workflow>.md (one prompt per key end-to-end behavior or change path)

Every prompt should be something a human can paste into a coding-agent session with minimal editing.

5. Separate Fact From Interpretation

For each section, use this standard:

• Observed: directly supported by code, tests, docs, or config
• Inferred: likely requirement or design intent derived from multiple signals
• Open question: ambiguity that cannot be resolved from the inspected evidence

If you are tempted to guess, write an open question instead. Keep these categories visible when writing the prompts. The prompt must not sound more certain than the evidence behind it.

6. Look For Contradictions

Before finalizing, check for mismatches between:

• docs and code
• tests and implementation
• config defaults and runtime assumptions
• interface definitions and actual handlers
• migrations/schema and data access code

When contradictions appear, document both sides and lower confidence. Do not silently reconcile them.

7. Write The Final Package

At minimum:

• context-manifest.md explains what was and was not analyzed
• evidence.md shows why the prompt suite says what it says
• README.md explains the prompt suite and recommended reading order
• prompts/ contains layered agent-facing specs

The prompt suite should be understandable without reading every evidence line, but every important instruction must be traceable back to evidence.

How To Write A Good Repo Prompt

Each prompt should contain most of these blocks:

• Goal
• Current repo reality
• What to preserve
• What can change
• Where to inspect first
• Constraints and non-goals
• Acceptance checks
• Evidence refs
• Open questions

This is the desired tone:

• direct
• collaborative
• specific
• implementation-aware
• not over-prescriptive unless the evidence demands it

This is the wrong tone:

• abstract product prose
• vague aspirations
• ungrounded architectural fantasies
• instructions with no finish line

Heuristics For Different Repo Shapes

Small Utility Or Library

Bias toward:

• public API
• supported inputs/outputs
• invariants
• compatibility promises

Backend Service

Bias toward:

• actors
• external interfaces
• data model
• workflows
• failure handling
• runtime configuration

Frontend App

Bias toward:

• user journeys
• state transitions
• API dependencies
• feature flags
• error and empty states

Monorepo

Bias toward:

• scope reduction first
• explicit module boundaries
• ownership assumptions
• dependency edges between packages/services

Anti-Patterns

• Reading random implementation files before understanding entrypoints
• Claiming product intent from naming alone
• Treating accidental current behavior as a normative requirement without caveats
• Writing a prompt-spec suite with no open questions
• Producing only a summary and skipping evidence.md
• Pretending a partial repo read is a whole-repo spec
• Writing a beautiful prompt that is not backed by repo evidence
• Writing one giant prompt when the repo really needs layered prompts

Completion Checklist

• Output lives under spec/
• README.md exists
• context-manifest.md exists
• evidence.md exists
• prompts/00-repo-brief.md exists
• prompts/01-system-spec.md exists
• prompts/modules/ contains prompts for major modules when applicable
• prompts/workflows/ contains prompts for key workflows when applicable
• major claims are traceable
• inferred items are labeled
• contradictions are documented
• open questions are explicit
• the result is a prompt-spec suite, not a file inventory

Final Response Pattern

When done, return:

• the output directory path
• the reading order of the generated prompt suite
• a short summary of what the repo appears to do
• the highest-confidence capabilities and prompts found
• the main uncertainties or missing evidence

If you could only analyze a bounded slice, say so directly.