Skip to content

How to Run OFT Trace

OpenFastTrace (OFT) verifies that every requirement is covered by design, implementation, and tests.

Generate the 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.

Read the report

Open the generated HTML report. Look for:

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

Common issues

dsn~ item needs utest but has none

A design spec declares Needs: impl, utest but no test file has a [utest->dsn~that-spec~1] tag. Add the tag to the relevant _test.go file.

"Unwanted coverage" warning

A [impl->dsn~wrong-name~1] tag references a spec that doesn't exist. Check for typos.

Tag syntax reference

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] */}}

In Markdown spec files

`dsn~my-design~1`

Description of the design.

Needs: impl, utest

Covers:

- req~some-requirement~1