---
name: motive
description: Author and track a named, persistent work thread with an Objective, open-items register, Decision Log, and Baselines.
---

# groundwork:motive

A motive is the durable container for an initiative's objective, its open items, and the decisions and events that shaped it. It lives entirely in `.groundwork/motives/<slug>/` (gitignored process state) and is separate from `doc/specs/`, which holds committed, public-facing outcome artifacts.

Not for session-only continuity (`groundwork:continue`), context handoff (`groundwork:handoff`), or committed requirement documents (`groundwork:spec`).

---

## Vocabulary

| Term | Meaning |
|---|---|
| **Motive** | Named work thread with a short `<slug>`. Stored under `.groundwork/motives/<slug>/`. |
| **Objective** | Single sentence captured at creation. Superseded via a new decision when the goal shifts — never edited in place. |
| **Charter** | Human-editable `motive.md`. Contains the Objective, TBD/TBR open-items register, and standing context. The open-items register is the authoritative source for unresolved questions. |
| **Open item** | A TBD/TBR row with a stable `id` (e.g. `TBD-2`). Resolved automatically when an `accepted` DECISION event carries `resolves: <id>`. |
| **Decision Log** | Compiled DECISION events. Generated by `journal compile`; never hand-edited. |
| **Baseline** | Named snapshot pin recording the journal ordinal at pinning time. |
| **Ticket** | Durable work object under `tickets/`. Filename: `NN-type-slug.md` (two-digit prefix; type from `research`, `choose`, `model`, `build`, `grill`, `spec`, `fix`, `chore`; kebab slug). Never auto-generated per ledger slice; never deleted by tooling. Scaffold: `node hooks/motive-ticket.mjs --help`. |
| **tickets/** | Durable store. Tooling creates a file only when none exists; human edits are preserved. |
| **open-items/** | Generated drill-down views swept on every regeneration. Use `tickets/` for durable objects. |
| **MAP.md** | Auto-regenerated human read path. Renders the ticket corpus with ledger status overlay. Never hand-edited. |

---

## Workflow

Full syntax and flags: `bin/journal help <cmd>` and `node hooks/motive-ticket.mjs --help`.

1. **Create** — `journal motive new <slug> --objective "…"`. Running it again without `--force` exits 1 and leaves the existing charter intact; `--force` overwrites.
2. **Edit charter** — Open `.groundwork/motives/<slug>/motive.md` directly. Add open items to the TBD/TBR register using the row format the template provides.
3. **Append events** — `journal append --motive <slug> --type <T> --msg "…" [--data '{}']`. For DECISION required/optional fields and revises/supersedes examples, see [`reference/decisions.md`](reference/decisions.md).
4. **Pin baseline** — `journal baseline <name> --motive <slug>`. Duplicate names are allowed — the latest write wins.
5. **Compile** — `journal compile <slug>` (flags: `bin/journal help compile`). The Decision Log in the compiled output is derived from events — it is never hand-edited. To correct a decision, append a new event with the corrected status or a superseding decision.
6. **Claim slice** (parallel sessions) — `ledger claim <id>`. A stale claim (from a session whose ledger is `active: false`) is reclaimable.

---

## Charter style

### Open-items register

Each entry follows a three-part shape:

```
- TBD-N: <plain-language sentence — what is open, readable cold; not a bare id or code path>
    <1–3 sentences: why it matters and what is at stake, then the open question or direction>
    refs: <D-ids, file:line, session ids>   ·   graduated-to: <ticket-stem>   (where applicable)
```

- The first line is a complete sentence. No bare D-ids, file paths, or jargon as the opener.
- The body leads with rationale (why it matters / impact), then the open question or direction.
- Machine citations — D-ids, `file:line`, session ids — belong on the trailing `refs:` line, not inline in the prose. Inline id-chains make an entry unreadable cold.
- No ALL-CAPS. No multi-deep decision-citation chains inline.

### Acceptance criteria

One criterion per bullet; one complete human sentence per criterion. Enforcement detail (file paths, schema keys, hook names) belongs in a trailing `note:` line on that bullet, not embedded in the statement.

### Tickets pointer

The charter does not duplicate the ticket list. Add a `## Tickets` section with a single pointer to `MAP.md` (the live auto-index); tooling keeps that file current.

---

## Negative scope

- Motive state (`.groundwork/motives/`, `.groundwork/compiled/`) is gitignored process state. Do not commit it.
- `doc/specs/` is the committed, public-facing outcome. Write specs there with `groundwork:spec`, not here.
- The Decision Log is compiled output — never edit it directly. Corrections flow through new events.