cta-format

Files (1)

• SKILL.md

SKILL.md (first lines)

# CTA Format — Canonical Specification

This skill is the **single source of truth** for the "Next Step" Call-to-Action block (the numbered Next-Step menu at the end of every pipeline command, one entry marked recommended) produced by every `/dr-*` command and every pipeline agent (`planner`, `architect`, `developer`, `reviewer`, `compliance`).

It exists because free-form Next-Step prose forces operators to mentally map task IDs to commands, especially when two or more tasks are active. The fix: every command output ends with a structured, predictable CTA block ([definition](../cta-format/SKILL.md)) with explicit task IDs and one marked primary action.

## When to Apply

- Any `/dr-*` command finishing its work — at the very end of the response.
- Any agent (planner / architect / developer / reviewer / compliance) returning control to the operator.
- After a phase boundary in `/dr-prd`, `/dr-plan`, `/dr-design`, `/dr-do`.
- After a QA / Compliance verdict (PASS, CONDITIONAL_PASS, BLOCKED, NON-COMPLIANT) — see § FAIL-Routing.

If a command intentionally produces no actionable next step (for example `/dr-help`, `/dr-status` in read-only mode), it MUST still emit a CTA block listing pipeline-entry commands.

`/dr-explain` is a presentation-only exception: answer the requested question and
preserve machine formats; do not append an execution CTA or invent a task header.

## Stage Header (canonical for /dr-* responses)

Every task-scoped `/dr-*` command and CTA-emitting agent MUST begin its operator-visible response with a one-line **Stage Header** (the `**{TASK-ID} · {title}**` banner emitted at the start of every pipeline command) so the operator can immediately tell which task the output belongs to. The header sits at the *opposite* end of the response from the CTA block: CTA = footer (what to do next), Stage Header = banner (what we are working on right now). Operators may run 40+ concurrent tasks; without the header, multi-task context is ambiguous.

### Format

```
**{TASK-ID} · {title}**
```

| Element | Rule |
|---------|------|
<!-- gate:history-allowed -->
| `{TASK-ID}` | Full prefix-number form, for example `ARCA-0001`, `TUNE-0262`. Never a short form, never paraphrased. |
<!-- /gate:history-allowed -->
| Separator | U+00B7 MIDDLE DOT `·` (the same character used in `tasks.md` one-liners). Surround it with single ASCII spaces. |
| `{title}` | Title verbatim from the `tasks.md` one-liner — the substring between `L{N} · ` and ` → tasks/`. No truncation, no paraphrase. Schema cap ≤80 chars. |
| Markdown | Bold inline (`**…**`) — matches the CTA footer convention (`**Next step — {ID}**`). No additional formatting, no headers, no surrounding blockquote. |

### Placement

- **First line** of the operator-visible response — before any tool-call narration, summary, or prose.
- Emitted exactly **once per command invocation**. Do not repeat the header in subsequent tool responses, follow-ups, or after each phase boundary inside the same invocation.
- If the command produces purely silent tool execution with no text output, the header MAY be skipped — there is nothing to label.

### Exception List

The following commands and contexts MUST NOT emit a Stage Header:

| Command | Rationale | Handling |
|---------|-----------|----------|
| `/dr-help` | No single-task context. | Skip the header entirely. |
| `/dr-explain` | Read-only re-explanation, potentially no task context. | Skip the header entirely. |
| `/dr-status` | Multi-task list; the command itself prints every ID. | Skip the header entirely. |
| `/dr-doctor` | Framework operation, not task-scoped. | Skip the header entirely. |
| `/dr-init` (Steps 1-3, pre-ID) | TASK-ID is not yet assigned. | Emit the header on the first line *after* Step 4 completes (once the TASK-ID has been determined). |
| `/dr-quick` (Step 1, pre-ID) | TASK-ID is not yet assigned (claim-surface collision probe in Step 2 must complete first). | Emit the header on the first line *after* Step 2's probe completes (once the TASK-ID has been determined). |

### Edge Cases

- **Empty title** — impossible per schema; `tasks.md` one-liners always carry a title.
- **Title > 80 chars** — the schema cap upstream prevents this; total header length is ≤ ~99 chars in the worst case.
- **TASK-ID assignment mid-execution** — `/dr-init` and `/dr-quick` are in this state; every other command has a pre-bound ID before it emits any text. For both, the header is deferred until the TASK-ID is known (after the probe completes).
- **Multi-step / multi-message commands** — emit the header once, in the very first message; do not re-emit per phase.

### Enforcement

<!-- gate:history-allowed -->
Programmatic enforcement is opt-in via the Claude Code Stop hook at `dev-tools/hooks/dr-output-stop.sh`. When registered in the project's `.claude/settings.local.json § hooks.Stop[]`, the hook checks the first non-empty line of every assistant response against `^\*\*[A-Z][A-Z0-9]{1,9}-\d{4} · .+\*\*$` (Exception List above honoured: `/dr-help`, `/dr-status`, `/dr-doctor`, plus `/dr-init` until Step 4 emits the TASK-ID, plus `/dr-quick` until Step 2's probe emits the TASK-ID). Missing header on first occurrence → stdout JSON `{"decision":"block","reason":"..."}`; retry (`stop_hook_active=true`) degrades to stderr advisory (retry budget = 1). The same hook also enforces `human-summary.md § Output contract` when the user invoked `/dr-archive`, `/dr-compliance`, or `/dr-qa`. Opt-in instructions and the canonical `settings.json` snippet live in `documentation/how-to/dr-output-hook.md`.
<!-- /gate:history-allowed -->

## Canonical Block — Single Active Task

Resolve replies via `${DATARIM_RUNTIME:?}/skills/datarim-system/language-preferences.md`. Labels below are examples, never a fixed Russian/English language requirement.

The English example shape below defines structure. Translate presentation labels and purposes to the resolved reply language; command tokens, task IDs and lifecycle enums stay unchanged.


```markdown
---

**Next step — {TASK-ID}** (L{N}, {status})

1. `/dr-{command} {TASK-ID}` — **recommended** — {one-line purpose}
2. `/dr-{command} {TASK-ID}` — alternative — {one-line purpose}
3. `/dr-{command}` — {one-line purpose}

---
```


### Field rules

| Field | Rule |
|-------|------|
| Top/bottom separator | Markdown HR `---` (CommonMark, confirmed working in the Claude Code renderer). |
| Header | English example: `**Next step — {TASK-ID}** (L{N}, {status})`. `{TASK-ID}` MUST resolve to one currently-active task. |
| Number of options | Min 1, recommended 3, hard ceiling 5 (Miller / Hick / Chernev 2015). |
| Option syntax | `N. \`{command + args}\` — **recommended** / alternative / {plain text} — {purpose}`. |
| Primary marker | Exactly one localized primary recommendation marker per block (`**recommended**` in English). Never zero, never two. |
| Purpose clause | One sentence, ≤80 chars. Describe outcome, not mechanics. |
| Task ID inclusion | Every command that operates on a specific task MUST include the `{TASK-ID}` argument inline. Pipeline-entry commands (`/dr-status`, `/dr-help`, `/dr-init`) MAY omit it. |

## Canonical Block — Multiple Active Tasks (Variant B)

When `## Active Tasks` in `datarim/activeContext.md` lists more than one task, append an "Other active tasks" (other active tasks) section:


```markdown
---

**Next step — {CURRENT-TASK-ID}** (L{N}, {status})

1. `/dr-{command} {CURRENT-TASK-ID}` — **recommended** — {purpose}
2. `/dr-{command} {CURRENT-TASK-ID}` — alternative — {purpose}
3. `/dr-status` — view the full backlog

**Other active tasks:**
- {OTHER-TASK-ID-1} (L{N}) — `/dr-{recommended-command} {OTHER-TASK-ID-1}` — {1-3 word context}
- {OTHER-TASK-ID-2} (L{N}) — `/dr-{recommended-command} {OTHER-TASK-ID-2}` — {1-3 word context}

From Arcanada-one/datarim, MIT.

More from Arcanada-one/datarim