---
name: project-document-branch
description: Use when an emergent lesson, critical path, proposed PRD/architecture/plan change, or suspected regression should be captured without immediately changing mainline project docs.
---

# Project Document Branch

Use this skill to branch project truth before promotion.

## Rules

- Mainline docs contain promoted truth.
- Document branches contain proposed, experimental, rejected, or regressed truth.
- Do not promote a branch into PRD, architecture, or implementation docs without
  evidence and merge criteria.
- Store branches under `docs/doc-branches/DBR-###-topic/`.
- Use `.prd_plugin/templates/` when present.
- If the branch affects agent memory, tracking, decisions, or changelog state,
  include proposed `.prd_plugin/state/*.json` deltas instead of changing
  committed state silently.
- Promote state deltas only after evidence, source references, and
  `AGENT-*` / `SES-*` provenance are present.
- Create or update `HLT-*` findings for promoted branches that are missing
  evidence, anchors, merge decisions, or regression conditions.
- Use a `DBR-*` branch when an accepted `REQ-*` proposes changes to project
  truth that need evidence before promotion.
- Every `DBR-*` must have a promotion owner and explicit trigger: a branch is
  not left open indefinitely. Decide and record one of **promote** (evidence +
  merge criteria met → fold into mainline docs/state via `project-traceability-sync`),
  **keep** (still experimental → set a re-review date), or **close/reject** (with
  the reason). `project-traceability-review` is the periodic owner that surfaces
  proven-but-unpromoted branches for this decision.

## Parallel Tracking Branches

Tracking branches are the lightweight machine-readable profile of document
branching for parallel agents. They live under
`.prd_plugin/state/tracking-branches/` instead of the narrative
`docs/doc-branches/` shape.

Use this parallel-worker profile only when the user explicitly requested subagents
or parallel agent work. Use at most three child agents, and subagents
must not spawn subagents or delegate further. Tracking-branch availability is a
safety mechanism, not permission to create workers.

1. **Before fan-out**, the lead calls `prd_open_tracking_branch` once per worker,
   commits the resulting distinct `DBR-*.json` seeds, and passes each worker its
   branch ID and owner label through `PRD_TRACKING_BRANCH_ID` and
   `PRD_TRACKING_BRANCH_OWNER`, with `PRD_WORKER_SESSION=1`.
2. Each worker calls only `prd_update_tracking_branch` on its assigned branch.
   It does not edit canonical `.prd_plugin/state/*.json` files or allocate IDs.
3. After worker code branches and tracking files are merged, the lead calls
   `prd_promote_tracking_branch` serially. Promotion allocates any new `TRK-*`
   and `DBR-MERGE-*` IDs under the canonical lock, merges additive notes/links,
   rejects overlapping field conflicts, and is idempotent on retry.

Direct goal/create/update tools remain the lead or ordinary single-writer path.
When `tracking.branching.require_for_parallel_agents` is true, workers must use
their assigned branch. `tracking.branching.enabled: false` prevents opening new
branches but never prevents existing branches from being updated and drained.

The compact tracking profile does not require `BRANCH.md`, `EVIDENCE.md`, and a
merge checklist for every worker note; those requirements remain for narrative
document branches. Its JSON record carries owner, base snapshot, delta,
promotion, and provenance fields instead.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Before creating or promoting a branch, check for stale `DBR-*`, `REQ-*`,
`TRK-*`, and `HLT-*` records on the same topic. A stale branch should be
refreshed with current evidence, marked regressed/retired, or left as an
explicit health finding before promotion.

## IDs

- `DBR-###` for the branch.
- `DBR-DELTA-###` for proposed document deltas.
- `DBR-MERGE-###` for promotion/rejection decisions.
- `DBR-REG-###` for regression records.
- `MEM-###`, `TRK-###`, and `CHG-###` for proposed state changes when needed.
- `HLT-###` for health findings created or resolved by the branch.
- `REQ-###` for request-intake records that motivated the branch.

## Branch States

`observed`, `hypothesis`, `experimenting`, `proven`, `promoted`, `rejected`,
`regressed`, `retired`.

## Promotion Requirements

Promotion requires:

1. Evidence ID.
2. Code anchor, if applicable.
3. Test anchor, if applicable.
4. Telemetry query, if applicable.
5. Last verified commit.
6. Regression condition.
7. Merge decision.
8. State delta review, if the branch affects `.prd_plugin/state`.
9. Health finding review, if the branch creates or resolves `HLT-*` records.
10. Request graduation review, if the branch came from `REQ-*`.

## Output

Create or update:

- `BRANCH.md`
- `BRANCH.json` (machine-readable branch, delta, and merge-decision identities)
- relevant delta docs
- `EVIDENCE.md`
- `MERGE-CHECKLIST.md`
- proposed state deltas or state update notes, when applicable