Decisions

The workflow needed an entry point and a minimal traceability core.

The change is the entry point, and the requirement is the spec unit; both belong to the Tier-1 core. Use cases and goals are deferred to growth roles.

No mandatory use-case ceremony; the requirement is the durable contract a change addresses.

OpenSpec nests scenarios inside requirements, but antora-tracer is a flat typed graph.

Scenarios remain prose inside a requirement body, and a test verifies the requirement. A scenario role is a later growth option.

Coverage is tracked at requirement granularity; no scenario-level traceability yet.

Most choices are domain or specification clarifications, not architecture.

Record design as the decision role. Drop the ADR and design-concept distinction; add a design-concept role later if stable abstractions are needed.

One decision role; no forced decision-to-concept link.

In-place edits break the referential integrity of the traceability graph.

An approved requirement is immutable: a change to its meaning supersedes it with a new requirement. Typos may be edited in place.

Append-only requirements with a supersedes lineage edge; some document sprawl.

The core spec-driven-development preset’s change.adoc now carries a five-field template (Rationale, Outcome, Out of Scope, Open Questions, Notes), but tracer-spec extends minimal and owns its own guidance.

tracer-spec’s change role keeps the established three fields (Rationale, Outcome, Out-of-scope), matching CHG-004 and the current skill fallback.

tracer-spec and the core preset diverge on the change field set. The skill follows whatever the guidance declares, so divergence is tolerated, and Open Questions and Notes can be added later as growth.

Conformance verification has no home in the workflow: validate is structural, and apply self-reports its own evidence.

Fold the conformance check into tspec-archive as a gate before close, performed by a cold, read-only reviewer. Do not add a dedicated verify-change skill.

The skill count stays at six, and verification is always and only a precondition to close, so the verified state remains self-claimed by apply.

MADR structures per-option advantages and disadvantages as a separate "Pros and Cons of the Options" section, but tracer-spec decisions are flat AsciiDoc labeled lists.

Nest each option’s good and bad as sub-bullets under Options, keeping the field list flat as Context, Options, Decision, Rationale, and Consequences.

Field derivation and AsciiDoc rendering stay uniform, options are enumerated once, and a reader sees each alternative with its trade-offs inline.

The tracker is a tracer-spec orchestration concern, but the workflow’s only configuration file is traceability.yml, which belongs to the antora-tracer core. Placing tracker settings there would make tracer-spec inject content into a file owned by a dependency it adds onto.

A tracer-spec-owned tspec.yml.

traceability.yml belongs to antora-tracer, which has no dependency on tracer-spec; tracer-spec is an independent add-on and should own its configuration.

Two configuration files. The tspec-track skill reads tspec.yml directly, and the command-line tool stays thin.

A change item must reference its tracker issue. Two candidate forms: a trackerId header attribute or a tracker:<id>[] relation macro.

A trackerId= attribute.

The issue is a pointer, not a traceability item; the parser already stores arbitrary attributes, so no core change is needed and validation stays quiet.

The link is inert to antora-tracer — not validated, not in matrices — which is intended; tspec-track reads it from the item header.

Both a change and its tracker issue carry a status; if both own it, they drift. Two candidate models: bidirectional sync or a link with one-way status push.

A link with one-way push.

The acceptance gate is already human; the agent mirrors the human’s decision into the tracker. Reconciliation adds complexity with no benefit to spec traceability.

Tracker-driven state changes are ignored by design. Teams that want the tracker to be the execution source of truth mirror it manually, or a future change adds an explicit pull path.

Tracker interaction spans propose (link or create), apply and archive (status push), and a new import path. It could be folded into the existing lifecycle skills or centralized in one.

One tspec-track skill.

Provider specifics change together and should live together; keeping them in one skill leaves the six lifecycle skills provider-agnostic.

The lifecycle skills stay unchanged; tspec-track is the single place to add or fix a provider.

Requirement statements leak implementation detail. Candidates: strengthen the propose skill, add a validation rule, or add a reviewer.

Strengthen the propose skill’s Rules with a self-check that references the requirement guidance’s "Solution prescription" list.

Semantic leakage cannot be linted; the cheapest effective lever is a self-check at authoring time, reusing the flag list the guidance already defines.

Reduces but does not eliminate leakage; the human accept gate and the archive cold reviewer remain the backstops.

Each skill could get its own how-to page, or the workflow could be documented as one task. Candidates: seven per-skill pages, one combined page, or one page now with a split later.

One combined how-to page now; split a skill into its own page only when that skill’s section grows real standalone steps.

The seven skills are phases of one task, so a single walkthrough models the workflow accurately; splitting is a mechanical cut with no rework when a section outgrows the page.

Keeps the how-to section at two pages (scaffold + workflow); per-skill detail lives in the reference catalog where it belongs.

guidance/change.adoc and guidance/decision.adoc are targets of traceability.yml roleGuidance, and their template content overlaps workflow/authoring.adoc. Candidates: move them into reference/, or keep them and fold the overlap.

Keep the guidance pages in place; fold the duplicated template content into reference/roles.adoc.

The pages are config-coupled, not ordinary docs; moving them buys layout purity at the cost of a traceability.yml edit with no functional gain.

roleGuidance paths stay stable; workflow/authoring.adoc is removed and its content lands once in reference/roles.adoc.