voyage/templates/trekbrief-template.md

---
type: trekbrief
brief_version: "2.2"
created: {YYYY-MM-DD}
task: "{one-line task description}"
slug: {slug}
project_dir: .claude/projects/{YYYY-MM-DD}-{slug}/
research_topics: {N}
research_status: pending         # pending | in_progress | complete | skipped
auto_research: false             # true if user opted into Claude-managed research
interview_turns: {N}
source: {interview | manual}
# v5.5 — framing: how this brief relates to prior operator intent. REQUIRED at
# brief_version ≥ 2.2. One of: preserve | refine | replace | new-direction.
# AskUserQuestion-validated in /trekbrief Phase 2.5 BEFORE any brief prose is
# written — the first layer of the framing-alignment defense (guards against the
# plan polishing a wrong premise after a rejected iteration).
framing: {preserve | refine | replace | new-direction}
# Size class (ceremony by size), said aloud in the /trekbrief question round and
# overridable by the operator; it only ever moves up mid-task. Optional: absent
# reads as architectural (the heaviest). One of: small | bounded | architectural.
ceremony: {small | bounded | architectural}
# Where the brief and plan live: git (committed) or local (kept out of git via
# .git/info/exclude). The approval log is committed either way. Optional: absent
# reads as local. Asked once per task in the /trekbrief question round.
artifact_store: {git | local}
---

# Task: {title}

> Generated by `/trekbrief` on {YYYY-MM-DD}.
> This brief is the contract between requirements and planning. `/trekplan`
> reads it to produce the implementation plan. Every decision in the plan must
> trace back to content in this brief.

## TL;DR

*≤ 5 lines. The framing-anchored one-glance summary: what this brief asks for and
how it relates to prior operator intent (framing: {preserve | refine | replace |
new-direction}). Written FIRST so a reader catches a wrong premise before reading
the full brief. Required at brief_version ≥ 2.2.*

{≤5-line summary.}

## Intent

*Why are we doing this? What is the motivation, user need, or strategic context?
3-5 sentences. Load-bearing for the plan — every implementation decision must
trace back to this intent.*

{Intent paragraph. Answers "why bother?".}

## Goal

*What does success look like concretely? What state will the system be in when
this is done? 1 paragraph. Specific enough to disagree with.*

{Goal paragraph.}

## Non-Goals

*What is explicitly out of scope? Prevents plan-critic and scope-guardian from
flagging gaps for things we deliberately do not do.*

- {non-goal 1}
- {non-goal 2}

## Constraints

*Technical, time, or resource limitations. Hard boundaries the plan must respect.*

- {constraint 1}
- {constraint 2}

## Preferences

*Preferred patterns, frameworks, libraries, or approaches. Soft constraints
(the plan may deviate with justification).*

- {preference 1}
- {preference 2}

## Non-Functional Requirements

*Performance, security, accessibility, scalability, or other quality attributes.
Quantified where possible.*

- {NFR 1 — e.g., "p95 response time < 200ms"}
- {NFR 2 — e.g., "Zero new npm dependencies"}

## Threat Model

*Optional: write it only when the task touches a guard, a gate, untrusted input,
secrets or publishing, and leave the whole section out otherwise (absent = every
security finding counts). One line per bullet, each `- Inside: <text>` (what the
work must defend against) or `- Outside: <text>` (what it deliberately does not);
any other bullet makes the brief invalid (`BRIEF_THREAT_MODEL_MALFORMED`).
Voyage's own security findings block inside it; one that quotes an `Outside:`
line's text exactly becomes a listed known issue. The intent approval covers
this section: editing it afterwards makes the approval stale.*

- Inside: {e.g., "a crafted file name in a pull request reaches the shell"}
- Outside: {e.g., "a local user who can already edit the repo's hooks"}

## Success Criteria

*Falsifiable, command-checkable conditions that define "done". Each must be
verifiable by running a specific command or observing a specific system behavior.*

- {criterion — e.g., "All existing tests pass: `npm test` exits 0"}
- {criterion — e.g., "New endpoint answers ok: `bash tests/health.sh` exits 0 (the script calls the endpoint and checks the status field)"}
- {criterion — e.g., "No TypeScript errors: `npm run typecheck` exits 0"}

Each command is written by the `voyage:writing-criteria` skill: the first
backticked span on the line, one command the criteria runner accepts, a script
under `tests/` for anything more, and able to go red. Otherwise the review
reports the criterion as NOT RUN.

Do NOT write vague criteria:
- "It should work" (not testable)
- "The feature is implemented" (not falsifiable)
- "Performance is acceptable" (no baseline given)

## Research Plan

*Explicit research topics that must be answered before `/trekplan` can
produce a high-confidence plan. Each topic is phrased as a research question ready
to feed into `/trekresearch`. Topics may be empty (N=0) for trivial tasks
where the codebase alone is sufficient context.*

{If research_topics = 0, write a single line: "No external research needed —
the codebase and this brief contain sufficient context for planning."}

### Topic 1: {Short title}

- **Why this matters:** {How the plan depends on this answer. Which steps or
  decisions cannot be made confidently without it.}
- **Research question:** "{Exact question to feed to /trekresearch.
  One sentence, ends in `?`.}"
- **Suggested invocation:** `/trekresearch --project {project_dir} --external "{question}"`
- **Required for plan steps:** {which kinds of steps will consume this — e.g.,
  "migration strategy", "library selection", "threat model"}
- **Confidence needed:** {high | medium | low}
- **Estimated cost:** {quick — inline research | standard — agent swarm | deep — with contrarian}
- **Scope hint:** {local | external | both}

### Topic 2: {Short title}

- **Why this matters:** ...
- **Research question:** "..."
- **Suggested invocation:** `/trekresearch --project {project_dir} ...`
- **Required for plan steps:** ...
- **Confidence needed:** ...
- **Estimated cost:** ...
- **Scope hint:** ...

## Open Questions / Assumptions

*Things still uncertain after the interview. These are carried as `[ASSUMPTION]`
entries into the plan and flagged to the user for review.*

- {question or assumption 1}
- {question or assumption 2}

## Prior Attempts

*What has been tried before and what happened. Leave blank for fresh tasks.
Prior attempts are load-bearing — they prevent the plan from repeating known
failures.*

{Prior attempts narrative, or "None — fresh task."}

## Metadata

- **Created:** {YYYY-MM-DD}
- **Interview turns:** {N}
- **Auto-research opted in:** {yes | no}
- **Source:** {trekbrief interview | manual}

---

## How to continue

Manual (default):

```bash
# Run each research topic (order does not matter):
/trekresearch --project {project_dir} --external "{Topic 1 question}"
/trekresearch --project {project_dir} --external "{Topic 2 question}"

# Then plan:
/trekplan --project {project_dir}

# Then execute:
/trekexecute --project {project_dir}
```

Auto (opt-in during `/trekbrief`): research and planning run
automatically; only execution is manual.