cadence-first

name	cadence-first
description	Meta-orchestrator: assigns skill-chain cadence per block (Tier 1/2/3) via Q1-Q6 rules. Reads target task_blocks + task.md, writes cadence-decisions-{R}.md artifact. Standalone (executor invokes) or Batch (generator hand-off). Use when: deciding cadence for a batch of blocks, generator hand-off from decomposition skills

Cadence-First Protocol

Assigns one of three tiers per block:

• Tier 1 Full — flow-first → library-first → plan-first → execute → ship-first
• Tier 2 Partial — library-first → plan-first → execute → ship-first
• Tier 3 Plan-focused — plan-first → execute → ship-first

Rules live in CADENCE_HEURISTICS.md (colocated). This SKILL is the executor; the manifest is the source of truth, read conditionally.

Does NOT execute the block itself. Decides cadence, then hands off.

---

Step 0 — Check task context

Are {log_dir} and {slug} known in the current session?

If yes → continue. If no → list latest task folders, ask which is current, set {slug} and {log_dir}. Cannot skip — without {log_dir} the artifact cannot be saved.

---

Step 1 — Parse invocation mode

1.1 Detect standalone vs batch

Signal	Mode
ARGUMENTS has task_id=X block_nums=[...]	Standalone
Invoked from generator context (parent inherits state)	Batch
No args, no context	Standalone (ask user)

1.2 Extract parameters

Standalone: parse task_id, block_nums from ARGUMENTS. Batch: inherit from parent. If missing → ask.

1.3 Anti-recursion guard

If task_id == {slug} (framework session's own task) → warn and default to abort. Prevents writing into the framework session's own task.

1.4 Verify task exists

Query the routing DB for id={task_id}. Empty → abort with "task not found".

---

Step 2 — Read sources (minimal by default)

2.1 Read target task_blocks

sqlite3 {routing_db} \
  "SELECT block_num, title, type, atom_type, status, recommended_cadence
   FROM task_blocks
   WHERE task_id='{target_task}' AND block_num IN ({block_nums_csv})
   ORDER BY block_num"

Defensive column check: PRAGMA table_info(task_blocks) | grep recommended_cadence. Column exists → write_to_db=true. Missing → markdown only.

2.2 Read target task.md

Extract task type/scope, ## Blocks table if present, HIGH-risk tags.

2.3 Scan landscape artifacts

List recent artifacts in the target log_dir. Look for {layer}-plan-{code}.md, recent flow-first-*.md, note-*.md claiming landscape coverage, roadmap docs referenced in task.md.

Landscape found → Q2 signal "skip flow". Absent → Q2 signal "keep flow".

2.4 HEURISTICS.md — CONDITIONAL read

Do NOT read by default. The cheat sheet below is authoritative. Read the manifest only when:

• Q1-Q6 answer ambiguous on ≥1 block → read the section for that Q
• Distribution alarm → read anti-pattern + ratios sections
• Output shape doubtful → read canonical spec
• Retroactive on legacy task → read legacy migration section

---

Q1-Q6 Cheat Sheet

Q	Question	Answer → signal	Effect
Q1	Block changes PROD code / state?	title has push/deploy/migrate/schema/prod → YES. Doc/research titles → NO.	YES + Q4 NO → Tier 1 lock. YES + Q4 YES → Tier 2 batch cycle
Q2	Landscape captured in adjacent artifact?	plan doc / prior flow-first / note claims landscape → YES. First block, no context → NO.	NO → flow-first mandatory (min Tier 1). YES → skip flow, continue
Q3	New library-vs-scratch decision?	First-of-kind / new integration / new schema → YES. Sibling of audited / trivial mechanical / doc → NO.	YES → keep library-first (Tier 2). NO → skippable
Q4	Deliverable = doc / diagnostic / mechanical batch?	note/spec/audit/smoke/verify/finalize titles → YES. N-identical mechanical → YES. Sibling mirror of audited block → YES.	YES → Tier 3 plan-only. NO → Tier 2 default
Q5	HIGH-risk override?	Explicit HIGH tag / silent-failure watchpoint / cross-cutting / discovery-heavy / rollback-complex → YES.	YES → Tier 1 override regardless of Q1-Q4
Q6	Block CREATES lib primitive consumed by downstream?	Title has "extract to lib" / new file in lib/ referenced later → YES. Consumer using existing lib → NO.	YES → Tier 1 anchor + FLAG if consumer's block_num < producer's

Q6 ordering check

For each Q6=YES producer, verify producer.block_num < min(consumer.block_num). If violated → warn user with concrete swap suggestion. Do not silently INSERT consumer-first ordering. User confirms swap or overrides with explicit rationale.

---

Step 3 — Apply Q1-Q6 per block

For each block: answer Q1→Q6, consolidate to tier via matrix.

3.1 Tier matrix

Q1	Q2	Q3	Q4	Q5	Tier
YES	—	—	NO	NO	1
YES	—	—	YES	NO	2 (batch cycle)
NO	NO	—	—	NO	1 (flow-first needed)
NO	YES	YES	NO	NO	2
NO	YES	NO	YES	NO	3
NO	YES	NO	NO	NO	2 (median)
any	any	any	any	YES	1 (override)
any	any	any	any	Q6=YES	1 (lib-first anchor + ordering check)

Store per-block: tier + Q-triggers rationale (yes/no + detected signal per Q) for Step 4.

3.2 Distribution sanity check

• >70% Tier 1 → warn "possible uniform-cycle bias — verify HIGH-risk classifications"
• >80% Tier 3 → warn "possible under-classification — flag skill-writing blocks for elevation"

---

Step 4 — Generate output (canonical shape)

Verbatim format. No column reorder, no rationale omission, no shape drift.

4.1 Main table

## Cadence decisions — {target_task}

| # | Block title | Flow | Library | Plan |
|:-:|---|:-:|:-:|:-:|
| {N} | {title} | ✓/✗ | ✓/✗ | ✓/✗ |

Tier mapping: Tier 1 → ✓✓✓, Tier 2 → ✗✓✓, Tier 3 → ✗✗✓.

4.2 Rationale per block

### Rationale per block

**Block {N} — {title}:** 1-3 sentences citing Q-triggers with detected signals.

4.3 Aggregate observations (optional)

Fire if pattern spans blocks OR distribution warning triggers.

---

Step 5 — Write artifact + routing.db

5.1 Round number

Scoped to target task's log_dir, not framework session's.

5.2 Write cadence-decisions-{R}.md

Header referencing target task.md, main table, rationale per block, aggregate observations if any, plus per-block Q-trigger audit trail (Q1-Q6 signals + assigned tier).

5.3 Register in task_artifacts

INSERT with artifact_type='cadence-decision'.

5.4 UPDATE task_blocks.recommended_cadence (defensive)

If write_to_db=true, UPDATE per block. Missing column → skip UPDATE, log warning. Existing non-NULL → prompt override, default preserve prior decision.

5.5 Append to task.md ## Task files

---

Step 6 — Hand-off

Standalone

Chat summary: artifact path, blocks analyzed, distribution counts, manifest version, any warnings. Full table + rationale already shown in Step 4.

Batch (called from generator)

Return structured JSON to caller: task_id, artifact_path, manifest_version, per-block {block_num, tier, cadence}, warnings. Batch does NOT print table to chat — the generator handles output.

---

Anti-patterns

❌ Applying baked heuristics without version check

Read HEURISTICS when Q ambiguous / distribution alarm / shape doubt. Don't apply outdated baked heuristics.

❌ Framework recursion

task_id equals framework session slug — cadence-first writes into its own task. The Step 1.3 guard is mandatory.

❌ Output shape drift

Format change → manifest patch first, never SKILL-only. Consumers depend on the exact shape.

❌ Silent override of existing cadence

Existing non-NULL → prompt override, default preserve prior decision. Never silently overwrite.

❌ Inlining Q1-Q6 evaluation

Executing the logic manually without invoking the tool — no artifact, no audit trail. Always via Skill('cadence-first').

---

When to read HEURISTICS.md

Trigger	Read section
Q1-Q6 answer ambiguous	the section for that Q
Distribution warning	anti-pattern + ratios
Output shape doubt	canonical spec
Retroactive on legacy task	legacy migration
Manifest version check	frontmatter

Otherwise: skip. The cheat sheet above is authoritative.

---

Related skills

• decomposition skills — invoke batch mode after generating a block list
• flow-first / library-first / plan-first — sub-skills whose invocation cadence-first decides; NOT invoked by this skill
• dev-auto-first — auto-invokes cadence-first before each block cycle

---

Step 99 — Log invocation

sqlite3 {routing_db} \
  "INSERT INTO skill_invocations (task_id, block_num, skill_name, invoked_at)
   VALUES ('{slug}', '{N}', 'cadence-first', datetime('now'))" 2>/dev/null || true