# Golden Rules

Non-negotiable rules enforced across all workflow stages.

---

## The Rules

### 1. Every Status Transition Gets a Comment

No silent state changes. Use templates from `reference/comment-templates.md`.
The surface enforces this — `issue_transition` requires a `comment` argument,
and so does `issues.py transition`.

### 2. Assignment Before In Progress

An issue cannot move to Implementing without an assignee. This is a hard gate.
`issue_activate` carries the assignee, the transition and the session state in
one call, so there is no half-activated state to leave behind. Script fallback:
assign → metadata → transition, in that order. Never skip assignment.

### 3. Checkboxes in Description — Change Them with `issue_acceptance_update`

Acceptance criteria progress is tracked by checking boxes in the issue description.
Change them with `issue_acceptance_update`, addressing criteria by id (script
fallback: `issues.py acceptance REF --check N`) — not by rewriting the whole
description and not in a comment. The relay merges the single criterion line under
a revision check, so a concurrent prose edit survives.
Never put completion marks in comments. Never create new checkboxes in comments.
See the Checkbox Protocol in `stages/implement.md`.

### 4. Use the Workflow Surface — Execute, Don't Describe

For all issue operations (create, transition, comment, assign, query), use the
MCP tools on the `flydocs` server; where none exists, use `flydocs run` or the
dispatcher script. The invocation matrix in `SKILL.md` says which is which. Run
it. Do not say "you should run..." or describe what a call would do. Execute and
report the result.

### 5. Session Wrap Posts a Project Update

Every session wrap posts a project update. `session_wrap` posts it itself — that
is what satisfies this rule; `project_update` is for mid-session updates only.
Fallback: `flydocs run session.wrap --health H`. Do not just summarize in chat.
Actually post. See `session.md` for the full protocol.

### 6. Product Scope Filtering

`issue_list` (and `flydocs run issue.list`) automatically applies product scope
from config using this cascade:

1. **`activeProjectId` set** → scope to that project
2. **`workspace.product.labelIds` set** → scope to issues with ALL those labels (AND logic)
3. **Neither set** → team-wide (no additional filter)

Explicit `--project` flag always overrides the cascade. The `--active` and `--status` flags
work within the scoped results — they do not bypass product scope.

Never show out-of-scope issues, even if the user asks.

### 7. Sequential Execution

Run workflow operations **one at a time, sequentially** — tools, runner and
scripts alike. Never fire multiple `issue_*` / `session_*` calls, or multiple
`flydocs run` invocations, in parallel. The relay API does not handle concurrent
requests from the same workspace well — parallel calls may timeout, produce
empty output, or silently fail.

Wait for each call to return before making the next. If you need to create
multiple issues, create them one by one and confirm each succeeds before
proceeding.

---

## Verification Gates

After executing any workflow operation, verify the result before responding:

| Action    | Call                                      | Verify                                            |
| --------- | ----------------------------------------- | ------------------------------------------------- |
| Capture   | `issue_create`                            | Issue identifier returned                         |
| Refine    | `issue_transition` → READY                | `ok: true`                                        |
| Activate  | `issue_activate`                          | Assignee set and state = IMPLEMENTING             |
| Implement | `issue_get`                               | Issue details loaded                              |
| Block     | `issue_transition` → BLOCKED              | `ok: true`                                        |
| Review    | `issue_transition` → REVIEW/TESTING       | `ok: true`                                        |
| Validate  | `issue_transition` → TESTING/IMPLEMENTING | `ok: true`                                        |
| Close     | `issue_transition` → COMPLETE             | `ok: true`                                        |
| Wrap      | `session_wrap`                            | Update posted (`project_update` action succeeded) |

The script fallbacks verify the same way, on the same steps — see the invocation
matrix in `SKILL.md`.

If any call fails: **stop, report, retry, escalate.** Do not continue to the next
step. A refused call comes back with the state it found and the way out — act on
that text rather than guessing a second route.

---

## Error Recovery

1. **Stop** — Don't continue to the next step
2. **Report** — Tell the user what failed
3. **Retry** — Attempt the failed step again
4. **Escalate** — If still failing, ask the user for help