voyage/templates/trekbrief-template.md

type	brief_version	created	task	slug	project_dir	research_topics	research_status	auto_research	interview_turns	source	framing	ceremony	artifact_store
trekbrief	2.2	YYYY-MM-DD	{one-line task description}	slug	.claude/projects/{YYYY-MM-DD}-{slug}/	N	pending	false	N	interview | manual	preserve | refine | replace | new-direction	small | bounded | architectural	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):

# 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.