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, or an empty result. Blocks dependents until you Retry or Diagnose it.

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)
  • Surface area — small, medium, or large
  • 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

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 → multi-perspective audit → fix critical issues → refactor → re-audit → documentation → consolidation → human gate

Failed Stories: Retry & Diagnose

When a story can't get through — its attempts are exhausted, a merge conflict can't be auto-resolved, its PR was closed externally, an audit rejected it, or the implementer produced no changes — it lands in the Failed state instead of stalling. The detail view shows a Details card with the failure cause and a short reason.

Two actions clear it:

  • 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), opens a read-only diagnostic chat to investigate what went wrong on that run. Submitting your findings returns to the gate and kicks off the retry path.

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.

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)

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.