Openfasttrace Reverse Specs

OpenFastTrace Reverse Specs

Reverse-engineer OFT specifications from existing project artifacts. Treat user-facing documentation as the primary source for intent and source code as evidence for implemented behavior and design.

Use the bundled templates when creating new documentation:

• assets/system_requirements_template.md
• assets/design_index_template.md
• assets/design/*.md

For OFT syntax and trace behavior, use the openfasttrace-skill if it is available in the session.

Operating Rules

• DO NOT change any code. The only exception are coverage marker comments in Step 3.
• DO NOT change the documents from which you reverse engineer specification (user guide, README).
• Preserve existing project specification documents unless the user explicitly asks to replace them. If a target file exists, patch it carefully or create a clearly named draft beside it.
• Keep a source inventory while working. For every inferred requirement or design item, know whether it came from user guide, README, tests, source code, configuration, build files, issue text, or runtime behavior.
• Prefer explicit evidence over speculation. Mark weakly supported conclusions in Open Issues.
• Do not hide contradictions. Summarize them in the final answer and record them in the generated document's Open Issues section.
• Use stable OFT item IDs in lower-kebab-case unless the project already uses another convention.
• Use revision ~1 for newly inferred items unless replacing an existing item with a semantically incompatible version.
• Keep generated text in draft status when confidence is incomplete.

Evidence Order

Inspect artifacts in this order:

1. User guide, manual, tutorial, screenshots, examples, CLI help, public API docs, README usage sections, and release notes.
2. Existing requirements, design, architecture decision records, issue plans, and trace files.
3. Tests, examples, fixtures, and golden files, especially acceptance, integration, CLI, API, and UI tests.
4. Public entry points in code: commands, controllers, UI actions, service APIs, plugin extension points, exported classes, configuration keys, and error messages.
5. Internal code structure, dependency declarations, build scripts, packaging, deployment manifests, and runtime integration points.

The user guide is closest to product intent. If code and user guide disagree, prefer neither silently. Record the contradiction and ask the user to decide.

In absence of a user guide, tests are the next best option to extract product intent.

Preconditions

OpenFastTrace (OFT) should be available to be able to check the created specifications.

If it is not installed, download the JAR artifact from OFT's latest GitHub release (https://github.com/itsallcode/openfasttrace/releases) and use that for the trace.

Use oft in the commands below. If only the JAR is available, replace oft with java -jar /path/to/openfasttrace.jar.

Trace Commands

Run traces with the narrowest artifact scope for the current reverse-engineering phase. The -a switch is a whitelist of artifact types included in the scan.

System Requirements Only

Run this after Step 1 to check feature, requirement, and scenario links inside doc/system_requirements.md:

oft trace -a feat,req,scn doc/system_requirements.md

Expected result: feature, requirement, and scenario links are complete. Downstream design coverage is intentionally out of scope in this trace, even when scenarios declare Needs: dsn.

System Requirements to Design

Run this after Step 2 to check coverage from system requirements down to design:

oft trace -a feat,req,scn,constr,dsn doc/system_requirements.md doc/design.md doc/design

Expected result: scenarios are covered by design items or OFT forwarding notation. Implementation and test coverage are intentionally out of scope.

Full Project Coverage

Run this after Step 3 to check coverage from requirements through design, implementation, tests, and build markers:

oft trace .

Expected result: the full requirement network is covered across all project files.

Decision Checkpoints

Use decision checkpoints to resolve open issues without derailing the reverse-engineering pass.

At the end of Step 1 and Step 2, summarize unresolved issues as a numbered list of concrete questions. For each question, include the conflicting or missing evidence, the decision needed, and a recommended default when the evidence supports one. If the user answers, update the document and remove resolved issues. If the user cannot answer or does not answer yet, keep the issue in Open Issues and keep the affected items in draft status.

Ask earlier only when a contradiction blocks writing a traceable draft.

Step 1: Draft System Requirements

Create or update doc/system_requirements.md using assets/system_requirements_template.md.

Build the document in this order:

1. Write the introduction from the user guide and README, not from implementation structure.
2. Define terms and user roles before feature details.
3. Extract product-level feat items from user-visible capabilities. Extract features sparingly. The level of granularity should be what would be listed on a product flyer.
4. Refine each feature into req items that describe user-visible needs and constraints.
5. Add scn items as Given-When-Then acceptance scenarios.
6. Add Needs and Covers links:
   • feat items need req.
   • req items cover feat and need scn.
   • scn items cover req and need dsn.
7. Fill gaps from tests and code only after user-guide-derived intent is represented.
8. Record uncertain inferences, missing intent, duplicate behavior, and contradictions in Open Issues.
9. Run a Decision Checkpoint for open issues that affect system requirements.
10. Run the System Requirements Only trace. Verify the trace is clean for the included artifact types.
11. After drafting system requirements, stop for user review unless the user explicitly requested a complete requirements-and-design reverse-engineering pass in one turn. Ask the user to remove the draft marker from requirements they reviewed and approved.
12. Report draft / total counts by artifact type and overall.