From 647602ca3a5a3c3a748dc7cc4c9344ca6a1ed61d Mon Sep 17 00:00:00 2001 From: redcatbear Date: Thu, 7 May 2026 14:31:25 +0200 Subject: [PATCH 1/3] #510: Add reverse specs skill --- skills/openfasttrace-reverse-specs/SKILL.md | 202 ++++++++++++++++++ .../agents/openai.yaml | 4 + .../assets/design/architecture_decisions.md | 38 ++++ .../assets/design/building_block_view.md | 33 +++ .../assets/design/constraints.md | 45 ++++ .../assets/design/context_and_scope.md | 33 +++ .../assets/design/crosscutting_concepts.md | 27 +++ .../assets/design/deployment_view.md | 31 +++ .../assets/design/glossary.md | 13 ++ .../assets/design/open_issues.md | 23 ++ .../assets/design/quality_requirements.md | 44 ++++ .../assets/design/risks_and_technical_debt.md | 15 ++ .../assets/design/runtime_view.md | 25 +++ .../assets/design/solution_strategy.md | 23 ++ .../assets/design_index_template.md | 61 ++++++ .../assets/system_requirements_template.md | 112 ++++++++++ .../references/evidence_checklist.md | 60 ++++++ 17 files changed, 789 insertions(+) create mode 100644 skills/openfasttrace-reverse-specs/SKILL.md create mode 100644 skills/openfasttrace-reverse-specs/agents/openai.yaml create mode 100644 skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/building_block_view.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/constraints.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/deployment_view.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/glossary.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/open_issues.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/runtime_view.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md create mode 100644 skills/openfasttrace-reverse-specs/assets/design_index_template.md create mode 100644 skills/openfasttrace-reverse-specs/assets/system_requirements_template.md create mode 100644 skills/openfasttrace-reverse-specs/references/evidence_checklist.md diff --git a/skills/openfasttrace-reverse-specs/SKILL.md b/skills/openfasttrace-reverse-specs/SKILL.md new file mode 100644 index 00000000..a3b8f15e --- /dev/null +++ b/skills/openfasttrace-reverse-specs/SKILL.md @@ -0,0 +1,202 @@ +--- +name: openfasttrace-reverse-specs +description: Reverse-engineer missing or incomplete OpenFastTrace system requirements and arc42-style design documentation from a project's user guide, existing documentation, tests, and code. Use when the agent must draft or repair `doc/system_requirements.md`, `doc/design.md`, and `doc/design/` chapters; infer features, requirements, scenarios, and design items; align design coverage with requirements; and report contradictions or open issues found during reverse engineering. +--- + +# 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](#step-3-add-coverage-markers-in-implementation-and-tests). +- 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`: + +```bash +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: + +```bash +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: + +```bash +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](#decision-checkpoints) for open issues that affect system requirements. +10. Run the [System Requirements Only](#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. + +## Step 2: Draft Design + +1. Create or update `doc/design.md` and `doc/design/` using: + + - `assets/design_index_template.md` + - files under `assets/design/` + +2. Derive design from code and tests, then match it against `doc/system_requirements.md`. + + Use this design structure: + + - Introduction and goals in `doc/design.md` + - Architecture constraints + - Context and scope + - Solution strategy + - Building block view + - Runtime view + - Deployment view + - Crosscutting concepts + - Architecture decisions + - Quality requirements + - Risks and technical debt + - Glossary + - Open issues + +3. Add `dsn` items where design decisions or runtime behavior cover `scn` and `constr` items. Prefer one runtime `dsn` per scenario or constraint. If a design layer adds no information, use OFT forwarding notation rather than inventing redundant design text. +4. If the documents contain information about intentional technical constraints, document them as `constr` in section `Architecture constraints`. Each `constr` item needs `dsn` coverage, and at least one `dsn` item must cover it. For example the project documentation states that only builds for x86 are supplied. Try not to infer constraints from the code, because they might not be intentional. +5. Record contradictions under `Open Issues`, especially when: + + - a scenario from system requirements is not implemented by the observed design, + - code implements behavior with no requirement, + - design structure conflicts with user-facing intent, + - tests assert behavior that differs from user-guide wording, + - public configuration or API behavior is undocumented, + - dependencies, persistence, network access, security, or deployment behavior contradict stated constraints. + +6. Run a [Decision Checkpoint](#decision-checkpoints) for open issues that affect design or design coverage. +7. Run the [System Requirements to Design](#system-requirements-to-design) trace. Verify the trace is clean for the included artifact types. +8. After drafting the design, 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. +9. Report draft / total counts by artifact type and overall. + +## Step 3: Add Coverage Markers in Implementation and Tests + +Do not change code logic. In this step, only add OFT coverage markers as comments. + +1. For each `dsn` item, read its `Needs` field and add exactly the requested downstream marker types: + + - `impl` for implementation code + - `utest` for unit tests + - `itest` for integration tests + - `stest` for system tests + - `bld` for build configuration + +2. Use the OFT tag notation `[->]` in the host file's comment syntax. Examples: + + - Java, JavaScript, TypeScript, C, C++, C#, Go: `// [impl->dsn~drop-database-objects~1]` + - Python, shell, YAML, TOML: `# [utest->dsn~drop-database-objects~1]` + - SQL: `-- [itest->dsn~drop-database-objects~1]` + +3. Place each marker directly above the smallest stable code element that implements or verifies the design item: method, function, class, test method, test class, build block, or configuration entry. Prefer narrow locations over file-level markers. +4. Do not add marker types that are not listed in the `dsn` item's `Needs`. If the observed project lacks the requested implementation or test evidence, do not invent coverage. Record the missing coverage in the design document's `Open Issues` section. +5. Run the [Full Project Coverage](#full-project-coverage) trace. Verify the trace is clean. + +## Reverse-Engineering Checklist + +Use `references/evidence_checklist.md` when the project is large or unfamiliar. + +For each feature area, collect: + +- intent source: guide, README, API docs, screenshots, examples, or release notes +- behavioral evidence: tests, examples, CLI output, UI actions, endpoint definitions, logs, errors +- design evidence: modules, packages, extension points, data flow, persistence, network calls, external systems +- verification evidence: unit tests, integration tests, acceptance tests, build gates +- confidence: high, medium, or low +- open issues: contradictions, missing source, unclear terminology, scope questions + +## Output Discipline + +When reporting back to the user: + +- summarize created or changed files, +- list contradictions and open issues first if any exist, +- state which evidence sources were used, +- state whether the next step is user review or design extraction, +- mention if OFT tracing was not run. + +Do not claim the reverse-engineered specification is complete. It is a structured draft until the user resolves intent and contradiction questions. diff --git a/skills/openfasttrace-reverse-specs/agents/openai.yaml b/skills/openfasttrace-reverse-specs/agents/openai.yaml new file mode 100644 index 00000000..01fc325b --- /dev/null +++ b/skills/openfasttrace-reverse-specs/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "OpenFastTrace Reverse Specs" + short_description: "Draft OFT specs from docs and code." + default_prompt: "Reverse-engineer missing OpenFastTrace system requirements and design documentation for this project." diff --git a/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md b/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md new file mode 100644 index 00000000..d5615273 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md @@ -0,0 +1,38 @@ +# Architecture Decisions + +This chapter records important architectural decisions and their rationale. + +Record a decision when it is hard to change later, likely to be debated again, relevant for cost or risk, or necessary to explain a non-obvious implementation choice. + +## `` + +### `` + +The project needs `` while ``. + +Considered alternatives: + +1. `` +2. `` + +#### `` +`dsn~~1` + +The system ``. + +Rationale: + +`` + +Status: draft + +Covers: +- `constr~~1` + +Needs: impl + +Tags: `` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/building_block_view.md b/skills/openfasttrace-reverse-specs/assets/design/building_block_view.md new file mode 100644 index 00000000..2c24a044 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/building_block_view.md @@ -0,0 +1,33 @@ +# Building Block View + +This chapter describes the static decomposition of the system into building blocks and responsibilities. + +## Component Overview + +`` + +```plantuml +@startuml +component "" as System +component "" as Component +System --> Component +@enduml +``` + +## Component Design Items + +### `` +`dsn~~1` + +`` + +Status: draft + +Covers: +- `scn~~1` + +Needs: impl + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/constraints.md b/skills/openfasttrace-reverse-specs/assets/design/constraints.md new file mode 100644 index 00000000..72752e17 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/constraints.md @@ -0,0 +1,45 @@ +# Architecture Constraints + +This chapter documents technical and organizational constraints that shape the architecture. + +## Technical Constraints + +* `` + +### `` +`constr~~1` + +`` + +Rationale: + +`` + +Status: draft + +Needs: dsn + +## Organizational Constraints + +* `` + +### `` +`constr~~1` + +`` + +Rationale: + +`` + +Status: draft + +Needs: dsn + +## Assumptions + +* `` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md b/skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md new file mode 100644 index 00000000..690bf5a1 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md @@ -0,0 +1,33 @@ +# Context and Scope + +This chapter describes the technical context, neighboring systems, external interfaces, and system boundary. + +Terms use the definitions from [System Requirements](../system_requirements.md). + +## System Boundary + +`` + +## Users and Neighboring Systems + +* `` + +## Supported Environment + +`` + +## External Interfaces + +`` + +## State and Persistence + +`` + +## Explicit Non-Goals + +* `` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md b/skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md new file mode 100644 index 00000000..3bf916fa --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md @@ -0,0 +1,27 @@ +# Crosscutting Concepts + +This chapter captures concepts that affect multiple parts of the architecture. + +## Domain Model + +`` + +## Configuration + +`` + +## Error Handling + +`` + +## Logging and Observability + +`` + +## Security and Privacy + +`` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md b/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md new file mode 100644 index 00000000..639dc5ae --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md @@ -0,0 +1,31 @@ +# Deployment View + +This chapter describes how the system is packaged and deployed in its execution environment. + +## Deployment Environment + +`` + +## Runtime Nodes + +The relevant deployment nodes are: + +* `` + +## Deployment Diagram + +```plantuml +@startuml +node "" { + component "" +} +@enduml +``` + +## Deployment Strategy + +`` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/glossary.md b/skills/openfasttrace-reverse-specs/assets/design/glossary.md new file mode 100644 index 00000000..4bd46b56 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/glossary.md @@ -0,0 +1,13 @@ +# Glossary + +This chapter defines design-specific terms used in the architecture documentation. + +General project terms are defined in [System Requirements](../system_requirements.md). + +## `` + +`` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/open_issues.md b/skills/openfasttrace-reverse-specs/assets/design/open_issues.md new file mode 100644 index 00000000..d898874b --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/open_issues.md @@ -0,0 +1,23 @@ +# Open Issues + +This chapter collects unresolved contradictions, missing intent, and weakly supported design conclusions found during reverse engineering. + +## Requirements and Design Mismatches + +* `` + +## Implemented Behavior Without Requirement + +* `` + +## Requirement Without Observed Implementation + +* `` + +## Contradictions Between Sources + +* `` + +## Decisions Needed + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md b/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md new file mode 100644 index 00000000..b1221c16 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md @@ -0,0 +1,44 @@ +# Quality Requirements + +This chapter documents architecture-relevant quality requirements and technical quality goals. + +User-facing acceptance scenarios are defined in [System Requirements](../system_requirements.md). + +## Requirement Quality + +Use this OFT hierarchy unless the project already defines a different one: + +1. `feat`: top-level feature +2. `req`: user requirement +3. `scn`: Given-When-Then acceptance scenario +4. `constr`: intentional architecture constraint +5. `dsn`: design requirement covering scenarios and constraints +6. `impl`: implementation +7. `utest`: unit test +8. `itest`: integration test + +Runtime design requirements `dsn` should cover one scenario or constraint at a time. Use OFT forwarding notation if a design layer adds no new information. + +## Code Quality + +`` + +## Test Quality + +`` + +## Dependency Policy + +`` + +## Static Analysis and Security Gates + +`` + +## Testability and Coverage + +`` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md b/skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md new file mode 100644 index 00000000..2df3e5a6 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md @@ -0,0 +1,15 @@ +# Risks and Technical Debt + +This chapter documents known architectural risks, limitations, and technical debt. + +## Risks + +* `` + +## Technical Debt + +* `` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/runtime_view.md b/skills/openfasttrace-reverse-specs/assets/design/runtime_view.md new file mode 100644 index 00000000..a0799ebd --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/runtime_view.md @@ -0,0 +1,25 @@ +# Runtime View + +This chapter describes relevant runtime interactions for the main use cases and extension points. + +Terms use the definitions from [System Requirements](../system_requirements.md). + +## `` + +### `` +`dsn~~1` + +**Given** `` +**When** `` +**Then** `` + +Status: draft + +Covers: +- `scn~~1` + +Needs: impl, utest + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md b/skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md new file mode 100644 index 00000000..f30babec --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md @@ -0,0 +1,23 @@ +# Solution Strategy + +This chapter summarizes the main technical approach for realizing the system requirements. + +## Main Technical Approach + +`` + +## Key Quality Drivers + +`` + +## Reuse of Existing Facilities + +`` + +## Data and Control Flow Strategy + +`` + +## Open Issues + +* `` diff --git a/skills/openfasttrace-reverse-specs/assets/design_index_template.md b/skills/openfasttrace-reverse-specs/assets/design_index_template.md new file mode 100644 index 00000000..4ec9fda6 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/design_index_template.md @@ -0,0 +1,61 @@ +# Design + +This document describes the architecture of ``. + +User perspective, audience, features, user requirements, and acceptance scenarios are defined in [System Requirements](system_requirements.md). This design document focuses on architecture, technical decisions, runtime behavior, and implementation structure. + +The structure follows arc42 with the user-perspective parts reduced to short references instead of duplicated content. + +## Structure + +### Introduction and Goals + +This design document explains how the system realizes the requirements defined in [System Requirements](system_requirements.md). + +### Architecture Constraints + +See [Architecture Constraints](design/constraints.md). + +### Context and Scope + +See [Context and Scope](design/context_and_scope.md). + +### Solution Strategy + +See [Solution Strategy](design/solution_strategy.md). + +### Building Block View + +See [Building Block View](design/building_block_view.md). + +### Runtime View + +See [Runtime View](design/runtime_view.md). + +### Deployment View + +See [Deployment View](design/deployment_view.md). + +### Crosscutting Concepts + +See [Crosscutting Concepts](design/crosscutting_concepts.md). + +### Architecture Decisions + +See [Architecture Decisions](design/architecture_decisions.md). + +### Quality Requirements + +See [Quality Requirements](design/quality_requirements.md). + +### Risks and Technical Debt + +See [Risks and Technical Debt](design/risks_and_technical_debt.md). + +### Glossary + +See [Glossary](design/glossary.md). + +### Open Issues + +See [Open Issues](design/open_issues.md). diff --git a/skills/openfasttrace-reverse-specs/assets/system_requirements_template.md b/skills/openfasttrace-reverse-specs/assets/system_requirements_template.md new file mode 100644 index 00000000..1ac28fe0 --- /dev/null +++ b/skills/openfasttrace-reverse-specs/assets/system_requirements_template.md @@ -0,0 +1,112 @@ +# System Requirements + +## Introduction + +Describe the product from the user's point of view. Base this section primarily on the user guide, README usage sections, tutorials, examples, public API documentation, screenshots, release notes, or CLI help. + +## Goals + +List the product goals inferred from user-facing documentation. + +* `` + +## Evidence Base + +This draft was reverse-engineered from: + +* `` +* `` +* `` +* `` + +## Notation + +This document uses OpenFastTrace specification items to express product features, user requirements, and acceptance scenarios. Each specification item has a unique identifier in the form `~~`. + +In this document, feature items use the artifact type `feat`, user requirements use `req`, and acceptance scenarios use `scn`. Design items in `doc/design.md` and `doc/design/` cover the scenarios with artifact type `dsn`. Architecture constraints in `doc/design/constraints.md` use artifact type `constr` and are also covered by `dsn` items. + +Informative text explains background, scope, and intent. Specification items define the normative content of the document. Relationships between items are expressed with OpenFastTrace keywords such as `Needs` and `Covers`. + +## Terms and Abbreviations + +### `` + +`` + +## User Roles + +Describe the people or systems that use, operate, administer, integrate, or maintain the product. Use the general term `user` only when a requirement does not depend on a specific role. + +### `` + +`` + +## Features + +This chapter describes product features at a level suitable for product communication. Detailed user needs and constraints are refined in the requirement items that cover these features. + +### `` +`feat~~1` + +`` + +Status: draft + +Needs: req + +## User Requirements + +The following requirements refine the product features into user-visible behavior, constraints, and quality expectations. + +### `` +`req~~1` + +`` + +Rationale: + +`` + +Status: draft + +Covers: +- `feat~~1` + +Needs: scn + +## Acceptance Scenarios + +The following scenarios describe observable behavior in Given-When-Then form. + +### `` +`scn~~1` + +**Given** `` +**When** `` +**Then** `` + +Status: draft + +Covers: +- `req~~1` + +Needs: dsn + +## Open Issues + +Record unresolved questions, contradictions, and weakly supported inferences. Do not remove an issue until the user has resolved it or a stronger source has been found. + +### `` + +Source evidence: + +* `` +* `` + +Issue: + +`` + +Decision needed: + +`` diff --git a/skills/openfasttrace-reverse-specs/references/evidence_checklist.md b/skills/openfasttrace-reverse-specs/references/evidence_checklist.md new file mode 100644 index 00000000..221194aa --- /dev/null +++ b/skills/openfasttrace-reverse-specs/references/evidence_checklist.md @@ -0,0 +1,60 @@ +# Evidence Checklist + +Use this checklist when reverse-engineering requirements and design from an unfamiliar code base. + +## User Intent Sources + +Search for: + +* `README*` +* `docs/`, `doc/`, `manual/`, `guide/`, `user_guide*` +* tutorials, examples, sample projects, demo scripts, screenshots +* CLI help, man pages, shell completion files +* public API docs, generated docs, OpenAPI specs, GraphQL schemas +* release notes, changelogs, migration guides + +Capture the user's vocabulary before writing item IDs or terms. + +## Behavior Sources + +Search for: + +* acceptance, integration, system, end-to-end, and golden-file tests +* examples and fixtures that encode expected outputs +* command handlers, controllers, routes, actions, jobs, schedulers, event handlers +* validation logic, error messages, warnings, logs, and exit codes +* configuration schemas, defaults, feature flags, and environment variables +* public interfaces, exported classes, package APIs, plugin extension points + +Use behavior sources to fill gaps after the user-guide intent is represented. + +## Design Sources + +Search for: + +* module, package, or component boundaries +* dependency injection configuration and service registration +* build files, dependency declarations, plugin descriptors, manifests +* persistence layers, schema migrations, repositories, caches +* network clients, external service integrations, protocols, file formats +* concurrency, background processing, retry, timeout, and cancellation logic +* security-sensitive code: authentication, authorization, secrets, sandboxing, input parsing + +## Contradiction Patterns + +Record an open issue when: + +* documentation describes behavior that tests or code do not implement +* tests assert behavior not mentioned in user-facing documentation +* two user-facing documents use different terms for the same concept +* code exposes configuration, commands, endpoints, or file formats with no documented intent +* implementation constraints contradict claimed portability, privacy, performance, or compatibility +* design dependencies or runtime behavior conflict with system requirements + +## Confidence Labels + +Use these labels in notes while drafting: + +* High: user-facing docs and tests/code agree. +* Medium: only one strong source exists, or source code and tests agree without user-facing docs. +* Low: inferred from internal structure only, or sources conflict. From d97c3edf87ae29c64e174255b77394eb78f2a52e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20B=C3=A4r?= Date: Thu, 7 May 2026 15:15:48 +0200 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sebastian Bär --- .../assets/design/architecture_decisions.md | 2 +- .../assets/design/deployment_view.md | 2 +- .../assets/design/quality_requirements.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md b/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md index d5615273..eb24ea94 100644 --- a/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md +++ b/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md @@ -8,7 +8,7 @@ Record a decision when it is hard to change later, likely to be debated again, r ### `` -The project needs `` while ``. +`` Considered alternatives: diff --git a/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md b/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md index 639dc5ae..7bbf9e01 100644 --- a/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md +++ b/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md @@ -13,7 +13,7 @@ The relevant deployment nodes are: * `` ## Deployment Diagram - + ```plantuml @startuml node "" { diff --git a/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md b/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md index b1221c16..8b101d75 100644 --- a/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md +++ b/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md @@ -11,7 +11,7 @@ Use this OFT hierarchy unless the project already defines a different one: 1. `feat`: top-level feature 2. `req`: user requirement 3. `scn`: Given-When-Then acceptance scenario -4. `constr`: intentional architecture constraint +4. `constr`: architecture constraint 5. `dsn`: design requirement covering scenarios and constraints 6. `impl`: implementation 7. `utest`: unit test From 6b1fe81d2bd71a5d0bcdb6e83045994a1548d798 Mon Sep 17 00:00:00 2001 From: redcatbear Date: Thu, 7 May 2026 15:27:26 +0200 Subject: [PATCH 3/3] #510: Add changelog entry --- doc/changes/changes.md | 1 + doc/changes/changes_4.3.0.md | 13 +++++++++++++ 2 files changed, 14 insertions(+) create mode 100644 doc/changes/changes_4.3.0.md diff --git a/doc/changes/changes.md b/doc/changes/changes.md index ea267619..4e1d9ffc 100644 --- a/doc/changes/changes.md +++ b/doc/changes/changes.md @@ -1,5 +1,6 @@ # Changes +* [4.3.0](changes_4.3.0.md) * [4.2.3](changes_4.2.3.md) * [4.2.2](changes_4.2.2.md) * [4.2.1](changes_4.2.1.md) diff --git a/doc/changes/changes_4.3.0.md b/doc/changes/changes_4.3.0.md new file mode 100644 index 00000000..ced0c3b5 --- /dev/null +++ b/doc/changes/changes_4.3.0.md @@ -0,0 +1,13 @@ +# OpenFastTrace 4.3.0, released 2026-05-07 + +Code name: Reverse specification skill + +## Summary + +In this release we added the OpenFastTrace Reverse Specs Skill. The skill guides AI agents through reverse-engineering missing system requirements and design documentation from a project's user guide, tests, and source code. + +The skill provides templates for `doc/system_requirements.md`, `doc/design.md`, and arc42-style design chapters. It also defines a user-guide-first workflow for capturing product intent, filling gaps from implementation evidence, and recording contradictions under Open Issues. + +## Features + +* #510: Added the OpenFastTrace Reverse Specs Skill for reverse-engineering missing specifications