PRD Planning Pipeline

The planning pipeline transforms your project's roadmap into a structured, executable PRD. It's a 5-phase pipeline that runs when you click Generate PRD — each phase is focused on one concern and writes its results to a shared draft file that the next phase reads.

How PRD Generation Works

Phase 1: Architect

Designs the high-level structure:

  • Phases — major development stages with clear objectives
  • Epics — groups of related work within each phase
  • Rationale — why things are organized this way
  • Complexity tier — simple / moderate / complex (affects guidance for downstream phases)

No stories are created yet — this phase focuses on getting the overall shape right.

Phase 2: Story Writer

Creates individual stories inside each epic:

  • Title, description, and acceptance criteria — clear, specific, testable
  • Story type — standard (most stories) or quality_checkpoint (inserted later by the Dependency Mapper)
  • Implementation scope — each story is sized to be independently executable by an agent

Phase 3: Dependency Mapper

Walks the story list and adds:

  • depends_on — which stories must complete before each one can start
  • Quality-checkpoint stories — new stories of type quality_checkpoint inserted at natural audit boundaries. These are story-level quality gates (intensive QA pipeline + human approval), not the same as a release's approval gate.

For large plans (>10 stories), the phase uses a 3-pass strategy (intra-epic → cross-epic within phase → cross-phase) running sub-agents in parallel per epic/phase.

Phase 4: Target Mapper

Assigns every story to the right project targets (Web App, API, Mobile, Desktop, CLI, Website, Library, Extension). Runs sub-agents in parallel per target batch. If the LLM misses any, Trinity auto-assigns all targets as a safe fallback — the pipeline never leaves a story without a target.

Phase 5: Calibrator

The Calibrator does two jobs: it verifies the Story Writer's descriptor hints, and it authors each story's execution settings.

Descriptors — verified comparatively across the whole plan, overriding outliers and enforcing a healthy distribution rather than a flat run of D3/medium ratings:

  • Difficulty (1–5) — how complex the implementation is
  • Surface area (small / medium / large) — how much of the codebase is touched

These two are read-only descriptors: they feed story-selection ordering and analytics, but they don't decide how a story runs. (On quality-checkpoint stories the Calibrator omits them entirely.)

Execution settings — the Calibrator authors three knobs on every story, using its judgment about the work rather than a formula off the descriptors. You can edit any of them later on the story page:

  • Audit passes — how many Auditor sweeps the story runs. Standard stories: 0 (skip) for throwaway work, 1 for the typical case, 2–3 for multi-concern or security-critical work (the Calibrator never goes above 3; you can raise it to 10). Checkpoints: the number of audit→fix iterations, floored at 1, typically 2–3.
  • Model tier — which model runs the implementation: reasoning (Opus) for genuinely complex or security-critical work, standard (Sonnet) for most stories, fast / micro for trivial mechanical changes.
  • Reasoning effort — low to max, defaulting to medium; raised for work that benefits from deeper reasoning. The run path clamps it down to whatever the resolved model actually supports.

Post-Pipeline Validation

After all five phases complete, Trinity runs an iterative validation + fix loop on the draft before it's saved:

  • Vague acceptance criteria — flags ACs containing weasel words like properly, appropriately, correctly, as needed, handle all, various
  • Dependency validation — catches circular dependencies, missing references, invalid cross-PRD IDs, and stories without any target assigned
  • Coverage check (full-PRD runs only) — compares the plan against the roadmap and flags gaps

Each iteration collects warnings, asks the agent to fix them directly in the draft file, re-reads the result, and repeats until the draft is clean or the max iteration count is hit. Calibrated fields (difficulty, surface_area) are restored if the fix LLM drops them.

Continuation Context (PRD 2+)

When generating a second or later PRD, the pipeline receives a continuation block assembled from prior work:

  • Full story manifests for every previous PRD — phases, epics, and per-story status (so cross-PRD depends_on can reference real IDs in the N:X.Y.Z format)
  • Gotchas recorded during execution of earlier PRDs
  • Already-done and failed stories with reasons (so the new PRD doesn't repeat failed attempts without a different approach)
  • Your user direction — what you want this next iteration to focus on

This block flows into every phase's prompt, so Architect can build on the existing structure and Story Writer can cross-reference previous work.

Plan Review Best Practices

After generation, review the plan before starting execution. The planning dashboard and story graph are the fastest ways to skim it.

Check Story Scope

Each story should be:

  • Specific — clearly defined, not vague
  • Independent — executable on its own (given its dependencies)
  • Testable — acceptance criteria an agent can verify

Verify Dependencies

  • Stories that should depend on each other but don't
  • Unnecessary dependencies that serialize work that could run in parallel
  • Missing quality checkpoints where you'd want Trinity to pause and verify things work together

Tune Execution Settings

The Calibrator does a good job, but you know your codebase best. To change how a story runs, open its Execution Settings card and adjust the audit passes, model tier, or reasoning effort directly:

  • Touching unfamiliar third-party APIs → consider raising the tier to reasoning and/or adding an audit pass
  • Story that's similar to existing code → consider a lower tier or 0 audit passes to avoid over-scrutiny
  • Security-critical / real-time / perf-critical → reasoning tier, higher effort, and more audit passes

(Difficulty and surface area are read-only descriptors — they don't change how a story executes, so there's nothing to adjust there.)

Check Quality-Checkpoint Placement

Quality-checkpoint stories are story-level quality gates — they run the intensive checkpoint pipeline (full-lens audit, refactor, re-audit, human approval) before downstream stories continue. Good placements:

  • End of a meaningful feature set
  • Before a major architectural shift
  • At boundaries where downstream stories depend on the earlier work being correct

Release-level approval (tagging, release notes, preflight) is a separate concept — see Releases.

Check Target Assignments

Target Mapper auto-fills any story it misses with "all targets", which is a safe fallback but often wrong. For polyrepos or multi-target projects, skim the story list to make sure each story is scoped to the right target(s) — a "set up mobile auth" story shouldn't be scoped to the web target.

Editing Stories

You can edit stories directly from the dashboard, graph, or stories list:

  • Click a story to open its detail view
  • Edit description, acceptance criteria, dependencies, targets, or the execution settings (audit passes, model tier, reasoning effort). Difficulty and surface area are shown read-only.
  • Changes save immediately

To drop a story you don't want, use Architect's removal flow — it deletes the story along with anything that depends on it as one reviewed change.

All edits are tracked in the activity feed.