Working with Stories

Stories are the atomic unit of work Trinity executes. Each story is sized to be completed end-to-end by one agent run through the 4-phase story pipeline (or, for quality checkpoints, the checkpoint pipeline).

Stories Page

Navigate to Stories in the sidebar's Project section. The page is release-scoped — it opens on the active release (persisted per-user, synced across your devices) and lists the stories of one PRD inside that release at a time. The release picker (top right) and PRD picker (filter row) drive what's rendered; both are required pickers, not optional filters. Deep link with ?prd=<id> to land directly on a specific PRD inside the active release.

List / Graph Toggle

A pill at the top of the page switches between the list view and the dependency graph. The toggle persists via the ?view=graph query param, and the graph rendered here is the same one documented on the Dependency Graph page — so a deep link with ?view=graph opens straight to the graph view of the current release / PRD.

Filters

Two dropdowns sit above the status tabs:

  • PRD — picks which PRD inside the active release to render (shown when the release has more than one PRD; defaults to the first PRD by sequence number)
  • Phase — narrow further to a single phase within the active PRD (shown as Phase 1, Phase 2, etc., with the phase name when available)

Epics are grouped under their phase in the list view — there's no separate epic filter, but each phase section has its own "all epics / specific epic" selector you can use inline.

Status Tabs

Tabs with live counts group stories by lifecycle status:

Tab Meaning
All Everything the filters returned
Pending Not yet started — still waiting on dependencies or for a worker to claim it
In Progress A worker has claimed the story and it's running through the pipeline
Completed All pipeline phases ran successfully; the story is merged into its branch and ready to ship
Merged Merged into the release branch (stories whose release is mid-staging show here too)
Released Part of a release that transitioned to released (so stories shipped with a git tag)
Already Done The Analyst found the work already satisfied and short-circuited before the Implementer ran — no diff, no PR. Counts as done and satisfies dependents without a merge.
Failed Execution didn't pass — attempts exhausted, a merge conflict, an externally-closed PR, an audit rejection, an authentication failure, or an empty result. Blocks dependents until resolved — see Failed Stories.

Two more states exist in code without a dedicated tab: blocked (stories with unmet dependencies the coordinator can't resolve — surfaced as a warning inside the Run page's Blocked Stories card) and staged (stories whose release is walking the staging chain — they appear under the Merged tab).

Story Detail

Click any story to open its detail view. Sections:

Description + Acceptance Criteria

Free-form description of what to build, plus a checklist of testable acceptance criteria. Agents use the ACs to verify their work before handing off.

Metadata

  • Display ID — prdSeq:phase.epic.story (e.g., 1:1.2.3 means PRD 1 / Phase 1 / Epic 2 / Story 3). This is the same format used in depends_on references and cross-PRD links.
  • Difficulty — 1 (trivial) to 5 (very complex), shown read-only. Describes the story for selection ordering and analytics; it does not drive how the story runs.
  • Surface area — small, medium, or large, shown read-only — same role as difficulty.
  • Story type — standard (most stories) or quality_checkpoint
  • Dependencies — other stories that must complete first
  • Targets — which project targets (Web App, API, Mobile, etc.) the story applies to
  • Tags — custom labels, including repo:<name> tags for multi-repo projects

Execution Settings

The Execution Settings card holds the three knobs that control how the story runs. The calibrator authors them during planning; you can edit each one here to override it. (Difficulty and surface area are shown read-only at the bottom of the card — they describe the story but don't set its execution behavior.)

  • Audit passes — how many times the Auditor sweeps the implementation (verify + simplify + review + check). 0 skips the auditor loop entirely; the typical value is 1; raise it for multi-concern or security-critical work, up to a cap of 10. On quality_checkpoint stories this control is labelled Audit → Fix Iterations and is the number of audit→fix cycles, floored at 1 — where 1 is an audit-only gate (it reports but doesn't auto-fix), and 2–3 fixes and re-checks until clean.
  • Model tier — which configured model runs the implementation phase: Reasoning (most capable), Standard, Fast, or Micro.
  • Reasoning effort — how hard the implementer reasons: Low, Medium, High, Extra High, or Max. A note below the control shows the effective effort for the model the selected tier currently resolves to — some models cap below Max, and a few (e.g. Haiku) take no effort setting at all.

Pipeline Status

When a story is running, you can see which agent phase it's in, the current operation, and any gate that's blocking progress. Which pipeline runs depends on story type:

  • standard stories — the 4-phase story pipeline: Analyst → Implementer → Auditor → Documenter
  • quality_checkpoint stories — the intensive checkpoint pipeline: analyze codebase → audit (all five review lenses) → fix critical issues → refactor → re-audit → documentation → consolidation → human gate

Failed Stories: Paths to Resolution

When a story can't get through, it lands in the Failed state instead of stalling — and a failed story is never a dead end: it carries an honest cause, it blocks its dependents (so nothing builds on missing work), and the architect drafts a way forward the moment it fails. Failing never deletes anything — branches, PRs, and repos that already merged keep their code.

The detail view shows a Details card with the failure cause and a short reason:

Cause What happened
retries exhausted Automatic attempts ran out — the retry threshold was hit, or you cut a story whose agent was stuck (outside the audit phase)
merge conflict A conflict (or a partially-failed multi-repo merge) couldn't be resolved and you cut the story at the merge gate
PR closed externally The story's PR was closed outside Trinity and you cut the story instead of recreating it
implementer produced no changes The implement run finished without producing a diff
audit criticals The audit phase escalated blocking findings it couldn't fix, and you cut the story
authentication failed A git operation hit an authentication failure and you declined to re-authenticate

The Architect's Proposal

Every failure files a dossier for the architect — the cause, the attempt count, the gate's details, conflict-resolution findings, and which stories the failure blocks — and the architect immediately drafts a resolution proposal from it, so the choice is usually ready by the time you open the story. The proposal renders as an Architect proposal card — on the story detail page, under the failed row on the Run page, and inside the run-stalled banner — with the rationale, the concrete changes, and two buttons:

  • Approve — applies the drafted resolution:
    • Retry as-is — nothing structural is wrong (say, the conflict has since been resolved upstream); the failure clears and the story re-queues on the next scan.
    • Reshape & retry — the story as written can't land; the proposal rewrites it (title, description, acceptance, dependencies, tags), then clears it for re-run.
    • Delete with reconciliation — the story shouldn't exist; the proposal removes it with an explicit decision for every story that depended on it — drop the dependency or repoint it — so nothing is left dangling.
  • Dismiss — sets the proposal aside; the story stays Failed for you to handle manually.

Retry & Diagnose

The manual paths stay available alongside the proposal:

  • Retry — clears the failure and resets the attempt count so the coordinator runs the story again from scratch.
  • Diagnose — on the failure gates (merge conflict, externally-closed PR, agent-blocked, hard-failed), opens a diagnostic chat to investigate what went wrong on that run. Submitting your findings returns to the gate and kicks off the retry path. A story that hits a hard failure (the implementer hung with no report, an agent timed out, or retries ran out) parks at the Story Failed gate for exactly this — see Gates → Story Failed.

How many times a story retries before it's marked Failed is governed by a retry-exhaustion threshold (default 3 attempts).

Agent Handoffs

Each phase posts a structured report when it hands off. Standard stories produce four reports (analyst, implementer, auditor, documenter); checkpoints produce their own set. Reports include decisions made, detected services, simplification passes, and vault entries written. The Handoff History shows each report with the time it was created and processed, so you can see how long each phase took.

Stack Items

Stories can be linked to stack items — the frameworks, databases, or tools they're responsible for introducing. During planning, the dependency mapper assigns unassigned items to the first story that will use them. After a story merges, the post-merge scanner verifies the assignments and flags mismatches as suggestions in Project Settings → Stack.

PR and Merge Status

For completed stories, the detail view shows:

  • Pull-request link + status per repo (in multi-repo projects, one row per repo)
  • Branch names used (derived from the project's branch template)
  • Merge status walking the configured staging chain (default story → dev → staging → production)

Reset story

The Reset story button (on the story detail view) takes a story all the way back to a clean slate so you can run it again from scratch. Resetting closes the story's open pull requests, deletes its branch and worktree, and clears its run history — its jobs, handoffs, and activity — leaving the story Pending with no run state. The confirm dialog ("Reset this story from scratch?") spells out exactly what gets removed before you commit.

Two guards protect you from a destructive mistake:

  • A merged or released story can't be reset — its code has already shipped, so the button doesn't appear.
  • A story that's currently running has to be stopped first; resetting never cancels a live run out from under a worker.

Reset is the right tool when a story went down the wrong path and you want a genuine fresh start, rather than Retry (which re-runs from the existing branch) or editing a Pending story in place.

Story Types

Standard (standard)

Regular development work — features, bug fixes, refactors. Flows through the 4-phase story pipeline.

Quality Checkpoint (quality_checkpoint)

Placed by the Dependency Mapper at natural audit boundaries (end of a feature set, before a major shift, anywhere downstream stories depend on earlier work being correct). Runs the intensive checkpoint pipeline with a mandatory human approval gate (which can be auto-approved via the autoApproveQualityCheckpoints setting — gate still logs for audit trail).

Quality checkpoints do not tag repos or ship a release — that's a separate pipeline, described in Releases.

Editing Stories

Pending stories are fully editable — open the detail view and change the fields inline; edits save immediately. Once a story is past pending — in progress, completed, merged, staged, released, already-done, or failed — it's protected from edits to avoid disrupting active or shipped work. If you need to change something that already ran, add a new story that builds on it (Architect is the clean way to do this).

All edits are tracked in the activity feed with field-level diffs.

Comments

Each story has a Comments tab (the count of comments shows next to the tab label). Comments are how you add clarifications or constraints to a story after it was written — "don't use X this time", "match the pattern in Y", "this needs to handle Z".

When the story runs, the Analyst and Implementer read every unresolved comment and treat it as a constraint: an unresolved comment overrides the default the agents would otherwise have chosen, and they call out in their handoff reports which comments shaped the work. Resolve a comment once it no longer applies and the agents ignore it.

This is the way to steer a story you can no longer edit. Pending stories are editable inline (see Editing Stories above); once a story is in progress or later it's locked — but a comment still reaches the agents on the next phase or re-attempt that reads the thread.

Automation Overrides (per-story)

Every story has an Automation tab letting you override settings just for that story. Overrides sit between the project-level default and the job-level config in the cascade:

Global → Team → User per-scope → Project → User per-project → Entity (story/release) → Job

Per-story overrides available:

  • Auto PR — open a PR automatically when implementation finishes
  • Auto-merge — merge when checks pass without waiting for you
  • Squash merge — squash commits on merge
  • Delete branch after merge — clean up after merging
  • Auto-approve quality checkpoints — skip the human gate on quality_checkpoint stories
  • Placeholder-audit toggles — fine-grained control over which placeholder categories the audit step flags

Leave any toggle unset to inherit from the project (or team / global) default. Overrides don't cascade to other stories. Model selection is project-level — set under Project Settings → AI Models — and is not overridable per story.

Multi-Repo Stories

In polyrepo / multi-target projects, one story can touch multiple repos. Each repo is tracked independently:

  • Separate branches per repo (each computed from the repo's branch template)
  • Independent PR + merge status per repo
  • repo:<name> tags on the release control which repos are tagged when the release ships (no repo tag = all repos tagged)

The story detail view groups per-repo state so you can see at a glance which repos are green vs. blocked.