Skip to content

OFT Requirement Tracing

This document explains how OpenFastTrace (OFT) requirement tracing works in the Wippidu project.

What is OFT?

OpenFastTrace is a requirement tracing tool that verifies every feature requirement is covered by design, implementation, and tests. It ensures nothing is "lost" between specification and code.

The tracing chain

Requirements flow through five levels:

feat~ (Feature)
  ↓ Covers
req~ (Requirement)
  ↓ Covers
dsn~ (Design)
  ↓ Covers
impl~ (Implementation)
  ↓ Covers
utest~ (Unit Tests)

Each level specifies what it covers (upward link) and what it needs (downward requirements). OFT verifies that every item's "Needs" are satisfied by items at the level below.

Where specifications live

Level File(s) Description
feat~ docs/tech/reqs/highlevel.md High-level feature requirements
req~ docs/tech/reqs/requirements.md Functional requirements
req~gui-* docs/tech/reqs/gui.md GUI-specific requirements
dsn~ docs/tech/arch/design.md Backend design specifications
dsn~gui-* docs/tech/arch/gui-design.md GUI design specifications
impl~ Go source files, HTML templates Implementation tags
utest~ *_test.go files Unit test tags

Tag syntax

In Markdown spec files

`dsn~my-design-name~1`

Description of the design specification.

Needs: impl, utest

Covers:

- req~some-requirement~1

The backtick-quoted identifier declares the spec item. Needs: declares what coverage is required. Covers: declares upward links.

In Go source files

// [impl->dsn~some-design~1]
func SomeFunction() { ... }

In Go test files

// [utest->dsn~some-design~1]
func TestSomeFunction(t *testing.T) { ... }

In HTML templates

{{/* [impl->dsn~gui-some-design~1] */}}
{{ template "layout/head" . }}

Tags can appear in package-level comments or function-level comments. OFT scans all files in the specified directories.

Running OFT

Generate a tracing report:

# Using the convenience script
./run_oft.sh

# Or manually
cd docs/tech
oft trace reqs/ arch/ ../../backend/internal/ ../../backend/cmd/ -o static/oft.html

The report is written to docs/tech/static/oft.html and embedded in the documentation via an iframe at OFT Report.

Reading the report

The OFT HTML report shows:

  • Green items: Fully covered — all Needs are satisfied
  • Red items: Missing coverage — some Needs are not met
  • "Unwanted coverage": A tag references a spec that doesn't exist (typo or removed spec)
  • Missing "In" links: An item has no implementation/test pointing to it

What to look for

When reviewing OFT output:

  1. dsn~ items that Needs: utest but have no [utest->...] pointing to them — tests are missing
  2. dsn~ items that Needs: impl but have no [impl->...] pointing to them — implementation is missing
  3. Items marked "unwanted coverage" — a tag references something that doesn't exist; fix the tag
  4. Duplicate tags — the same identifier appears more than once

Current status

See OFT Status for the current implementation coverage tables, and OFT Report for the generated HTML report.