me-cedric Codebase to specifications
Create the first documentation draft from code that already exists. Describe observed behavior. Do not present observed behavior as agreed intent.
Required warning
Put this warning directly below the title of every generated document:
> **Inferred from code, not reviewed.** Drafted from `<commit sha>`. Review this
> document before you use it as a source of truth.
Only a human reviewer can remove the warning.
Read the evidence
- Read the host
AGENTS.mdand its configured document paths. - Use the configured code graph before a broad repository search. Check index coverage for every path that supports a material or exhaustive claim.
- Read
README.md,CONTRIBUTING.md, and relevant files underdocs/. - Read the package or build manifests and the command registry.
- Read the observable surfaces: entry points, routes, handlers, jobs, migrations, schemas, and tests.
- Read recent commit subjects with
git log --oneline -50. Reuse the team's established terms.
Source code is authoritative for current behavior. Existing reviewed documents remain authoritative for intent. Report conflicts between them.
Bound the work
Group the code into capabilities: the small set of things the system does for a user or another system. Do not create one specification per file.
List all discovered capabilities. Draft the largest eight first. If more remain, list them under Not covered so the scope is visible.
Outputs
Use the host's configured paths. Use these defaults only when the host has no local convention.
| Document | Default path | Content |
|---|---|---|
| Capability specification | specs/<capability>/spec.md |
Inputs, outputs, rules, scenarios, questions, and gaps |
| Decision record | docs/decisions/NNN-<title>.md |
A consequential choice visible in the implementation |
| Architecture sketch | docs/diagrams/<system>.c4 |
Observed systems, containers, and relationships |
Every specification must include these sections:
Open questions
List facts the code cannot establish: unexplained constants, conflicting paths, unreachable branches, unclear ownership, and behavior that can be a defect or a requirement. Write each item as a question for a reviewer.
Not covered
List every scope you did not inspect and the reason: time limit, generated code, vendored code, missing access, excluded files, or incomplete graph coverage.
Rules
- Never invent a requirement to make a draft look complete.
- Never describe a likely defect as intended behavior. State the observed behavior and the concern separately.
- Never overwrite an existing specification or decision record. Write a draft beside it and name the conflict.
- Never infer intent from graph silence or missing tests.
- Never remove the inference warning.
- Never commit or push. Leave the drafts for review.
Report
Report:
- Capabilities found and drafted.
- Files written.
- Open questions, most consequential first.
- Evidence and scopes not read.
- Conflicts with existing documents.
The next action is human review of the open questions. That review turns an observed draft into an agreed specification.