Legacy Codebase Specification Recovery
Recover API contracts, business rules, side effects, and architecture from source with evidence links and explicit unknowns.
Before & after
Same prompt, same agent — the only difference is the skill.
You can analyze the code to understand how it works. Look at the function signatures and method names to get a sense of what's happening. Read through the implementation line by line and try to understand the logic flow. You could also look for comments or docstrings that might explain intent. Creating a summary as you go would help you build up understanding. It's tedious but doable with careful reading.
SPEC EXTRACTION: Payment API Handler
DISCOVERED ENDPOINTS
POST /api/payments/charge
INPUT: { amount: number, currency: 'USD'|'EUR', customer_id: string, metadata: object }
OUTPUT: { id: string, status: 'pending'|'completed'|'failed', error?: string }
SIDE EFFECTS:
-> Calls Stripe API (external)
-> Logs to Datadog
-> Updates customer.last_charge_at timestamp in database
ERROR HANDLING:
-> Network timeout (>10s): retries 3x with exponential backoff
-> Invalid amount (<0.50 USD): returns 400 'amount_too_small'
-> Unknown customer_id: returns 404
-> Rate limit (>100 req/min): returns 429, client backs off
GET /api/payments/status/:transaction_id
READ-ONLY, returns full transaction object including webhook_status
WEBHOOK: POST /webhooks/stripe
LISTENS FOR: charge.succeeded, charge.failed, dispute.created
ACTIONS:
-> succeeded: marks transaction complete, updates customer credits
-> failed: notifies customer via email, initiates retry
-> dispute: flags account for manual review, holds balance
KNOWN QUIRKS / BUGS
-> Webhook retry logic has 24-hour window (should be 72h per Stripe docs)
-> Currency conversion cached hourly; can be stale in volatile markets
-> No idempotency key support; double-POST = double-charge risk
DEPENDENCIES
-> Stripe v2024.03.0
-> Database: PostgreSQL transactions table
-> Message queue: Redis for async webhooks
-> Auth: Bearer token in Authorization header
TYPES (inferred from usage)
type Transaction = { id, amount, currency, customer_id, status, created_at, webhook_status, metadata }
NEXT STEPS
1. Add idempotency key to prevent double-charges
2. Extend webhook retry window
3. Document this spec in READMEAbout this skill
“We inherited this service with no docs. What does it actually do?” Recover a specification from the implementation, with source evidence for its rules, contracts, dependencies, and side effects. See which conclusions the code supports and which still depend on deployment settings or unavailable systems.
What it does
- Maps HTTP routes, CLI commands, scheduled jobs, and message consumers before tracing behavior.
- Extracts business rules with their exact conditions, precedence, exceptions, and enforcement points.
- Reconstructs API inputs, response branches, authorization checks, and error paths from reachable code.
- Identifies database writes, external calls, queue messages, transaction boundaries, and partial-failure risks.
- Builds source-linked dependency and architecture maps, distinguishing confirmed edges from unresolved dynamic wiring.
- Records the inspected revision, coverage limits, contradictions, and specific next checks.
What you get
An implementation-derived specification sized to your request: a focused behavior explanation, an API contract, or a broader system document with a dependency map. Material findings include source locations and evidence limits; inferred intent stays separate from implemented behavior.
Best for
Engineers inheriting undocumented services, teams preparing legacy migrations or refactors, and maintainers who need trustworthy documentation before changing unfamiliar code.
SKILL.md preview
---
name: legacy-codebase-specification-recovery
description: 'Recover implementation-derived specifications by tracing entry points through business rules, data access, side effects, and failure paths, with source evidence and coverage limits. Use when the user says "reverse engineer this service", "we inherited this codebase", "there are no docs", "figure out how this works", "document the API from source", "map the dependencies before a refactor", or "the docs keep disagreeing with the code".'
---
# Legacy Codebase Specification Recovery
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.