Skip to main content
Suspec
manual page/ Reference

Artifact formats

sourceSource: suspec/docs/reference/artifact-formats.mdModified: 2026-06-30
Sections
13
Format
Markdown
Order
22 / 156

Every Suspec file is markdown with frontmatter.

The type: field identifies the artifact.

Core types

TypePrefixHome
intakenoneintake/
specSPEC-specs/<feature>/spec.md
taskTASK-tasks/
reviewREVIEW-reviews/
findingFINDING-findings/
statusnonestatus.md

Conditional types

TypePrefixHome
inventoryINV-inventory/
change-planCHANGE-change-plans/

Advanced types

TypeUse
auditpresent-state risk or debt
bug-reportdiagnosis of one defect
adrdecision record
researchinquiry with sources, no decision
prdproduct requirements
rfcproposal for review
threat-modelsecurity analysis
release-noteshipped-change note

Intake

Frontmatter:

code
type: intake
source: SHOP-4012
url: https://...
captured: 2026-06-20

Body: verbatim source text.

No interpretation.

Spec

Frontmatter:

code
type: spec
id: SPEC-checkout
title: Expired checkout sessions
status: draft
owner: checkout-team
sources:
  - intake/SHOP-4012.md

Sections:

  • Intent
  • Non-goals
  • Requirements
  • Open questions
  • Affected areas
  • Dropped from sources, when needed
  • Execution — append-only run record, one dated entry per change-cycle

Each requirement has:

  • AC-NNN
  • one behavior
  • Verify with:

## Execution holds the run record. An entry may be prose or a structured change-record carrying Scope, Coverage (AC→evidence), and Pins (reviewed-sha: + evidence-hash:) — see ADR-0110.

Task

Frontmatter:

code
type: task
id: TASK-checkout-expiry
source:
  - SPEC-checkout
scope: [AC-001]
status: ready

Sections:

  • Source
  • Scope
  • Do not change
  • Affected areas
  • Verify
  • Agent instructions
  • Findings
  • Run summary

Every verify item names a requirement id.

status is one of:

  • ready
  • running
  • review-ready
  • closed

Review

Frontmatter:

code
type: review
id: REVIEW-checkout-expiry
task: TASK-checkout-expiry
pr: https://...
reviewer: name-or-session
status: draft

Sections:

  • Summary
  • Changed files
  • Requirement coverage
  • Change-plan coverage, when relevant
  • Human attention
  • Open decisions, when relevant
  • Task status
  • Suggested decision

Coverage rows use:

code
ID | Result | Evidence | Human attention

Results:

  • Pass
  • Fail
  • Unverified
  • Blocked

A Pass needs evidence.

Finding

Frontmatter:

code
type: finding
id: FINDING-session-expiry-is-409
from: REVIEW-checkout-expiry
date: 2026-06-20
related:
  - SPEC-checkout#AC-001

Sections:

  • What we learned
  • Evidence
  • Where it applies
  • Where it does not apply
  • related spec / task / review / file
  • Future guidance (optional)

One finding, one durable claim.

Status board

status.md is hand-edited.

It lists:

  • active specs
  • active tasks
  • review status
  • human attention
  • pending findings

Closed or verified rows link to their review packet while retained.

Inventory

Use before brownfield work.

Sections:

  • Scope
  • Observed structure
  • Interfaces
  • Tests
  • Unknowns
  • Risks

No prescriptions.

Change plan

Use for structural work.

Sections:

  • Baseline
  • Target
  • Preservation guarantees
  • Transformation waves
  • Cutover / rollback
  • Task split

Every wave names verification.

Reference rules

  • IDs are stable.
  • Accepted decisions are superseded, not rewritten.
  • Requirement IDs are spec-scoped.
  • Cross-spec references use SPEC-id#AC-NNN.
  • Code can falsify a spec; it does not amend it.

Starter kit: Set up a workspace