pm-workflow

name	pm-workflow
description	Use when starting a new feature, resuming a paused feature, advancing a phase, running the v6.0 10-phase product management lifecycle (Research → PRD → Tasks → UX/Integration → Code → Test → Review → Merge → Docs → Learn), OR managing the roadmap (RICE / MoSCoW / Now-Next-Later prioritization + decision memos). Orchestrates skill-on-demand dispatch, model tiering (Sonnet vs Opus), batch operations, deterministic phase timing, cache-hit tracking, eval coverage gates, and CU v2 continuous factors. Invocations: /pm-workflow {feature-name} | /pm-workflow roadmap {review|prioritize|decide {item}}.
last_updated	2026-05-15T00:00:00.000Z
framework_version	v7.8.6
status	active
adapters_used	["ga4"]

Product Management Lifecycle: $ARGUMENTS

You are orchestrating the feature "$ARGUMENTS" through the complete product management lifecycle. Every phase requires explicit user approval before proceeding to the next.

Preflight: Observed Patterns Catalog (v7.8.5+ — added 2026-05-13)

The pattern↔skill map tracks 71 work-blocking patterns (25 gate-firing patterns + 46 workflow patterns) drawn from the Observed Patterns Catalog (make observed-patterns). The patterns below are the ones mapped to /pm-workflow work — probe the mechanized ones, checklist the rest:

ID	Pattern	Blocker	Remediation
#1	BRANCH_ISOLATION_HISTORICAL — squash-merge + branch-cleanup artifact (probed)	no	Confirm squash-merge cleanup-artifact via PR head_ref; set isolation_opt_out + reason only if work was genuinely direct-to-main.
#2	CACHE_HITS_AUTO_INSTRUMENTATION_INACTIVE — Mechanism C captured, writer-path manual (probed)	no	Mid-workflow Reads captured but not yet persisted; log via scripts/log-cache-hit.py (v7.9 auto-writes).
#3	BRANCH_ISOLATION_VIOLATION Mode B — infra-only commit on non-feature branch (probed)	yes	Move the infra-path commit onto a feature/chore branch (isolated worktree); Mode B ignores isolation_opt_out.
#4	BRANCH_ISOLATION_VIOLATION Mode C — state.json current_phase mutation off-branch (probed)	yes	Work on the declared feature/chore branch, or set isolation_opt_out + reason when the branch field is legitimately stale.
#5	ISOLATION_OPT_OUT_REASON_MISSING — opt-out without justification (probed)	yes	Set isolation_opt_out_reason to a non-empty justification, or remove isolation_opt_out.
#6	FEATURE_CLOSURE_COMPLETENESS — missing frontmatter on current_phase=complete (probed)	yes	Populate the 7 required case-study frontmatter fields + kill_criteria_resolution before the complete-transition commit.
#7	CACHE_HITS_AUTO_INSTRUMENTATION_DRIFT — empty cache_hits[] post-v6 (probed)	yes	Log Reads via scripts/log-cache-hit.py; features created_at < 2026-05-02 are auto-exempt.
#8	TIER_TAG_LIKELY_INCORRECT — heuristic T1/T2/T3 mismatch (advisory permanent) (probed)	no	Verify the T1/T2/T3 tag; pin correct T1 values in case-study-t1-references.json or set tier_tags_present:false.
#9	SCHEMA_DRIFT_LEGACY_CREATED — legacy created key (probed)	yes	Rename the legacy created key to canonical in state.json.

At activation run make skill-preflight SKILL=pm-workflow — probes the 22 mechanized blockers for this work type; clear any before proceeding.

Mandatory (CLAUDE.md §v7.8.5): any novel pattern surfaced this session MUST be appended to observed-patterns.md before the feature closes — then re-run make gen-skill-preflight.

Skill Loading Protocol (v5.1 — On-Demand + Model Tiering)

Before starting any phase, check .claude/shared/skill-routing.json → phase_skills for the current phase. Load ONLY the listed SKILL.md files — do NOT load all 11 skills.

1. Read skill-routing.json → phase_skills[current_phase]
   • If the value is an array: use it as the skill list directly (v5.0 format, no tier)
   • If the value is an object: read .skills for the skill list, .model_tier for the tier recommendation
2. Load .claude/skills/{skill}/SKILL.md for each listed skill
3. For cache: load compressed_view fields from .claude/cache/ by default (≤200 words each)
4. Only expand full cache entries when the compressed view is insufficient — set expand_cache: true mentally

Why: Loading all 11 SKILL.md files costs ~38K tokens. Most phases need only 1-2 skills. On-demand loading saves ~30K tokens/session. Cache compression saves another ~24K tokens.

Fallback: If phase_skills is missing or load_mode is not on_demand, fall back to loading all skills (v4.4 behavior).

Model Tiering Protocol (v5.1 — ANE Mixed Precision)

After loading phase skills, check skill-routing.json → model_tiering for the current phase's recommended model tier.

1. Read the model_tier field from phase_skills[current_phase] (only present if value is an object)
2. If model_tiering.enabled is true and a tier is found, announce: "Recommended model: {tier} ({reason})"
3. Opus phases (judgment): research, prd, ux_or_integration, review
4. Sonnet phases (mechanical): tasks, implementation, testing, merge, documentation, learn

User override: The user can always override the tier recommendation. This is advisory, not enforced.

Fallback: If model_tiering is missing or enabled is false, default to opus for all phases.

Batch Dispatch Protocol (v5.1 — TPU Weight-Stationary)

When the user requests an operation that applies the same skill/command to multiple targets (e.g., "audit all screens", "validate analytics for all features"), use batch dispatch instead of individual invocations.

Detection

Batch dispatch is appropriate when:

• The user explicitly requests a multi-target operation ("audit screens X, Y, Z")
• Phase 0 of a parent feature spawns multiple child audits
• Analytics taxonomy sync needs to run across multiple features

Execution

1. Check skill-routing.json → batch_dispatch.supported_operations for a matching operation
2. If found: a. Load template once — read the template_source file into context b. Iterate targets — for each target, apply the template and collect results c. Aggregate — produce a single report with per-target sections d. Write individual — if output_pattern is set, write per-target files
3. If not found in supported_operations, fall back to sequential individual dispatches

Supported Batch Operations

Operation	Skill	Template	Targets
audit	/ux	ux-foundations.md	Screen files (Swift)
design_compliance	/design	design-system.json	UX spec files
analytics_taxonomy_sync	/analytics	analytics-taxonomy.csv	Feature PRD files

Example: Batch Audit

User: "Audit all 6 screens for v2 alignment"

1. Load docs/design-system/ux-foundations.md (template — load ONCE)
2. For each screen in [Home, Training, Nutrition, Stats, Settings, Onboarding]: a. Read the current v1 Swift file b. Apply UX foundations audit pattern c. Collect findings (P0/P1/P2 with tractability tags)
3. Produce aggregated report: v2-batch-audit-report.md
4. Write individual: .claude/features/{screen}/v2-audit-report.md per screen

Savings: 1 template load + N screen reads = N+1 reads. Without batch: N × (template + screen) = 2N reads. For N=6: 7 vs 12 reads + 5 fewer hub dispatch cycles.

Fallback: If batch_dispatch config is missing from skill-routing.json, each target is dispatched individually (v5.0 behavior).

Dispatch Intelligence Protocol (v5.2 — Pre-Flight + Routing)

Before dispatching any subagent, apply the 3-stage pipeline from .claude/shared/dispatch-intelligence.json:

Stage 1 — Score Complexity

Read the task's complexity field from tasks.md (lightweight/standard/heavyweight). If missing, default to standard.

Stage 2 — Probe Capability

Check target file paths against the permission_table in dispatch-intelligence.json:

• Path matches known_writable → dispatch to subagent
• Path matches known_readonly → controller handles directly
• Unknown path → dispatch haiku micro-probe (5 tool budget, 15s timeout)

Critical note: .claude/ paths are in known_writable in the table but subagents CANNOT write to them regardless of settings.json permissions. The controller must always handle .claude/ writes directly.

Stage 3 — Dispatch with Budget

Use model_routing config for the task's complexity tier:

• Include in prompt: "BUDGET: You have {N} tool uses for this task."
• Set model parameter: haiku (lightweight), sonnet (standard), opus (heavyweight)
• On budget hit: accept if usable, escalate if incomplete (max 1 escalation)

Escalation Path

lightweight (haiku) → standard (sonnet) → heavyweight (opus) → BLOCKED (report to user)

Dispatch Logging

Every dispatch logs to the checkpoint file for validation analysis:

{"task_id": "T1", "predicted_complexity": "standard", "model_used": "sonnet", "tool_budget": 25, "actual_tool_uses": 15, "actual_duration_seconds": 102, "result": "DONE", "quality": "no_rework"}

Mirror Pattern (v5.2B — Parallel Write Safety)

When dispatching an agent to modify a SHARED file (one that other agents may also modify):

Pre-dispatch:

1. SNAPSHOT the target file to .build/snapshots/{dispatch_id}/
2. EXTRACT the agent's region using 3-tier detection:
   • Tier 1: // BEGIN:agent-region:{name} markers → extract between BEGIN/END (fastest)
   • Tier 2: // MARK: - {Section} conventions → extract from MARK to next MARK (fast)
   • Tier 3: Full file → give entire file, flag for marker addition (slow, first-time penalty)
3. DISPATCH with region only + read-only type context (imports, signatures)

Agent prompt includes:

You are modifying this code region:
---
[extracted region]
---
Add your code within this region. Return ONLY the modified region content.

Post-return: 4. RECONSTRUCT the file by replacing the region at its boundaries 5. BUILD CHECK — run xcodebuild 6. If PASS: delete snapshot, add markers if Tier 3 was used, commit 7. If FAIL: ROLLBACK from snapshot, log error, redispatch or escalate

Progressive learning: Each Tier 3 dispatch that succeeds adds // BEGIN:agent-region:{name} / // END:agent-region:{name} markers. Next dispatch to the same region uses Tier 1 automatically. The system gets faster with every dispatch.

When NOT to use mirror pattern:

• project.pbxproj edits (use ID-prefix isolation instead — proven in stress test)
• Files only one agent will touch (no contention risk)
• Files under 50 lines (overhead exceeds benefit)

Phase Timing Protocol (v6.0 — Measurement Instrumentation)

Every phase transition now records precise timestamps in state.json → timing. This replaces estimated wall times with measured durations.

On Phase Start (after user approves transition)

1. Write timing.phases[{phase}].started_at = current ISO 8601 timestamp
2. If this is the first phase of the feature, also write timing.session_start = now
3. If resuming after a break, ask the user: "How long were you away?" and add the answer to the previous phase's paused_minutes

On Phase End (before requesting next transition approval)

1. Write timing.phases[{phase}].ended_at = current ISO 8601 timestamp
2. Compute timing.phases[{phase}].duration_minutes = (ended_at - started_at) in minutes
3. Update state.json → updated timestamp

On Feature Completion (current_phase → "complete")

1. Write timing.session_end = current ISO 8601 timestamp
2. Compute timing.total_wall_time_minutes = sum of all timing.phases[*].duration_minutes
3. Set timing.time_source = "measured"

Multi-Session Features

If a feature spans multiple conversations/sessions:

1. On session start: append a new entry to timing.sessions[] with started_at = now and phases_active = [current phase]
2. On session end: write ended_at and compute duration_minutes for the current session entry
3. timing.total_wall_time_minutes = sum of all timing.sessions[*].duration_minutes

Parallel Features

When multiple features are being worked on concurrently (stress tests, parallel dispatch):

1. Set timing.parallel_context.concurrent_features = count of active features
2. Set timing.parallel_context.concurrent_feature_slugs = list of other feature slugs
3. Set timing.parallel_context.is_stress_test = true if this is a deliberate parallel test

Cache Tracking Protocol (v6.0 — Deterministic Hit Logging)

Replace probabilistic cache health checks with deterministic per-event logging. Every cache access is recorded in .claude/features/{feature}/cache-hits.json.

On Skill Load (reading from .claude/cache/{skill}/)

1. Check if a cache entry exists for the current task type and context
2. HIT: Append to cache-hits.json → sessions[current].hits[]:

   {
     "timestamp": "{ISO 8601}",
     "cache_level": "L1|L2|L3",
     "skill": "{skill-name}",
     "cache_key": "{skill}:{task_type}:{context}",
     "hit_type": "exact|adapted",
     "task_context": "{task description from tasks list}"
   }
   

3. MISS: Append to cache-hits.json → sessions[current].misses[]:

   {
     "timestamp": "{ISO 8601}",
     "cache_level": "L1|L2|L3",
     "skill": "{skill-name}",
     "expected_key": "{key that was looked up}",
     "miss_reason": "no_entry|stale|wrong_context",
     "task_context": "{task description}"
   }
   

4. STALE (SHA256 of source file doesn't match invalidated_by hash): Log as miss with miss_reason: "stale"

Hit Type Taxonomy

• exact: Cache entry used directly without modification
• adapted: Cache entry used as a starting point but modified for current context
• stale: Entry existed but was outdated — counted as a miss

On Phase Completion

1. Compute session summary: count L1/L2/L3 hits and misses
2. Write total_hit_rate = total_hits / (total_hits + total_misses) to session summary

On Feature Completion

1. Finalize aggregate section in cache-hits.json (totals across all sessions)
2. Identify most_valuable_hit (entry that saved the most rework) and costliest_miss (pattern that had to be built from scratch)
3. Update .claude/shared/cache-metrics.json:
   • Increment by_framework_version[current].features_measured
   • Recompute avg_hit_rate and L1_avg/L2_avg/L3_avg
   • Add to cache_health_trend[] with date and hit rate
4. Check promotion candidates: any L1 entry hit by 2+ different skills → add to promotion_candidates[]

Velocity Annotation

When writing the case study, annotate velocity claims based on cache hit rate:

• hit_rate >= 0.6: velocity is framework-attributable (no annotation needed)
• hit_rate 0.3–0.6: annotate as "partial cache" — velocity partially reflects practitioner skill
• hit_rate < 0.3: annotate as "cold cache" — velocity may significantly reflect practitioner skill over framework

This annotation does NOT change the CU calculation. It adds interpretive context to min/CU comparisons.

Contemporaneous Logging Protocol (v7.5 — Tier 2.2 Auto-Emission)

This protocol supersedes the v6.0 Cache Tracking Protocol's separate .claude/features/{feature}/cache-hits.json writer path. The canonical Tier 2.2 writer is scripts/append-feature-log.py, which writes to .claude/logs/{feature}.log.json AND mirrors cache events into state.json.cache_hits[] so make measurement-adoption counts them. Filed as issue #140; shipped 2026-04-24. If the v6.0 instructions above conflict with this section, this section wins.

On every phase transition (auto-emit, not voluntary)

When the user approves a phase transition (Research → PRD, PRD → Tasks, etc.), the skill MUST append an event to the feature's log before any other write:

python3 scripts/append-feature-log.py \
  --feature {feature-slug} \
  --event-type phase_started \
  --phase {new-phase} \
  --summary "Phase {new-phase} opened after user approval of the {old-phase} exit criteria." \
  --actor claude_opus_4_7

Then, on phase end (before requesting the next transition):

python3 scripts/append-feature-log.py \
  --feature {feature-slug} \
  --event-type phase_approved \
  --phase {phase} \
  --summary "Phase {phase} complete. {1-sentence of what landed.}" \
  --artifact {list of files touched} \
  --metric tests_passing=N \
  --actor claude_opus_4_7

On any cache hit during work (Tier 1.1 writer path)

When the skill loads a cache entry (L1 per-skill, L2 shared, or L3 project) and the entry materially influenced the output, emit a cache-hit event using the v7.7 auto-discovering wrapper (added T2 / commit 448d989 branch):

python3 scripts/log-cache-hit.py \
  --key <cache-key> \
  --layer <L1|L2|L3> \
  [--hit-type <adapted|exact|miss>] \
  [--skill <skill-name>]

The wrapper auto-discovers the active feature by scanning .claude/features/*/state.json by mtime (most-recently-modified non-paused feature wins), so --feature is not required. It dual-writes: first to state.json.cache_hits[] directly, then delegates to scripts/append-feature-log.py for Tier 2.2 narrative logging. It is fail-soft — any error exits 0 with a warning to stderr so logging never breaks cache reads. The v7.7 T3 hook (CACHE_HITS_EMPTY_POST_V6, commit 448d989) gates current_phase: complete on at least one cache_hits[] entry, so this call is now required before a feature can be marked complete.

If you need to supply the feature name explicitly (e.g. the active-feature auto-discovery would resolve to the wrong feature), fall back to the direct invocation:

python3 scripts/append-feature-log.py \
  --feature {feature-slug} \
  --event-type cache_hit \
  --phase {current-phase} \
  --summary "Reused {cache-key} for {task description}. {What it saved.}" \
  --cache-hit L1|L2|L3 \
  --cache-key {entry-id} \
  --cache-hit-type exact|adapted \
  --cache-skill {skill-name}

Both calls append to the log AND to state.json.cache_hits[]. Prefer the wrapper for the normal case (no --feature arg needed = less friction = higher adoption).

On runtime verification events (Tier 2.1)

When make runtime-smoke PROFILE=<id> MODE=<local|staging> produces a passed or failed status, emit a runtime_verification event:

python3 scripts/append-feature-log.py \
  --feature {feature-slug} \
  --event-type runtime_verification \
  --phase test \
  --summary "Staging {profile} smoke {passed|failed}. {xcresult bundle link.}" \
  --artifact .claude/shared/runtime-smoke-staging-{profile}.json \
  --metric status={passed|failed} \
  --metric returncode={0|N}

Why auto-emit?

v7.5 Tier 2.2 shipped as "pilot active" specifically because adoption was voluntary — contributors had to remember to invoke the logger. This protocol makes emission automatic on the PM workflow's own transition events, eliminating the adoption gap.

The retroactive policy still applies: if the skill needs to append an event older than the most recent entry, it must use --retroactive --retroactive-reason "...". The logger enforces this.

What this does NOT do

• It does not auto-generate the narrative case study. That's still a Phase 9 deliverable written after merge.
• It does not replace state.json → timing instrumentation. Both coexist: timing is the measured-duration ledger; .claude/logs/ is the narrative event trail.
• It does not backfill the v6.0-era .claude/features/{feature}/cache-hits.json files — those are frozen as-is. Going forward, the log + state.json path is canonical.

Eval Coverage Gate Protocol (v6.0 — AI Quality Assurance)

Ensures AI-touching features have verifiable eval coverage before shipping. Non-AI features auto-pass.

During PRD Phase (AI-touching features only)

1. Identify all AI behaviors in the PRD:
   • Recommendations (nutrition, training, recovery)
   • Scoring (readiness, confidence, tier assignment)
   • Classification (cohort, goal-awareness, intensity selection)
   • Any output that depends on AI/ML logic
2. For each behavior, define minimum eval coverage:
   • Golden I/O evals: >= 3 per behavior (known-good input → expected output)
   • Quality heuristic evals: >= 2 per behavior (output meets quality bar)
   • Tier/edge case evals: >= 1 per behavior (boundary conditions)
3. Write the coverage plan to the PRD under ### Test & Eval Requirements
4. Store the full behavior list in state.json → phases.testing.eval_results.uncovered_behaviors

During Testing Phase

1. Run evals: cd ai-engine && pytest evals/ -v
2. Parse results and write to state.json → phases.testing.eval_results:
   • total_evals, passing, failing, eval_pass_rate
   • categories breakdown (golden_io, quality_heuristic, tier_behavior, etc.)
   • Update uncovered_behaviors — remove behaviors that now have evals
3. Gate check: min_eval_coverage_met = every behavior in the original list has >= 1 passing eval
4. If gate fails: BLOCK transition to Review phase
   • Display: "Eval gate failed: {N} behaviors still uncovered: {list}"
   • User can override with justification → record in transitions[].note: "Eval gate overridden: {reason}"
5. If gate passes: Set min_eval_coverage_met = true, proceed normally

Non-AI Features

• eval_results stays at defaults (total_evals: 0, passing: 0)
• min_eval_coverage_met auto-set to true
• Gate does not block

How to Detect AI-Touching Features

A feature touches AI if ANY of these are true:

• PRD references AIOrchestrator, ReadinessEngine, NutritionRecommender, TrainingRecommender, or CohortIntelligence
• state.json → has_ui is true AND the feature modifies views that display AI-generated content
• The task list includes changes to ai-engine/ directory
• The PRD has a "### AI Behaviors" or "### Recommendation Logic" section

Monitoring Sync Protocol (v6.0 — Auto-Update Case Study Monitoring)

Phase transitions automatically update case-study-monitoring.json. This replaces manual monitoring updates with structured, event-driven writes.

Phase Transition Triggers

Transition	Fields Updated in case-study-monitoring.json
research → prd	process_metrics.research_complete = true
prd → tasks	process_metrics.prd_approved = true
tasks → implement	process_metrics.tasks_defined = state.phases.tasks.count
implement → testing	process_metrics.repo_files_added and repo_files_updated from git diff --stat
testing → review	process_metrics.tests_passing, build_verified, ai_quality_metrics.eval_pass_rate, eval_total, eval_failed[]
review → merge	quality_metrics.critical_findings, high_findings, medium_findings from review
merge → docs	process_metrics.merged = true, pr_number from state.json
docs → complete	Add snapshot with label "feature-complete-auto-{ISO 8601}", write timing.total_wall_time_minutes

Snapshot Protocol

Every auto-sync also adds a snapshot entry:

{
  "timestamp": "{ISO 8601}",
  "label": "auto-sync-{from_phase}-to-{to_phase}",
  "metrics": { "/* current metrics at time of transition */" }
}

Fallback

If case-study-monitoring.json does not have an entry for the current feature:

1. Create one with the feature slug as case_id
2. Set status: "in_progress", framework_version, work_type from state.json
3. Then proceed with the sync

Manual Override

The auto-sync writes structured fields only. Narrative notes, decisions, and custom metrics are still added manually. Auto-synced snapshots are labeled with auto-sync- prefix to distinguish them from manually written ones.

Result Forwarding Protocol (v5.1 — UMA Zero-Copy)

When skills execute in a known chain (e.g., Phase 3 dispatch chain), pass the output of each skill inline to the next skill instead of writing to disk and re-reading.

When to Forward

Check skill-routing.json → result_forwarding.eligible_chains for the current skill transition. If a matching chain exists and result_forwarding.enabled is true:

1. Execute the source skill and capture its full output
2. Write to disk (always — for audit trail and fallback)
3. Forward inline — pass the output directly to the next skill in context
4. Tag the forwarded content with _forwarded_from: "{skill}:{command}" so the receiving skill knows it does not need to read from disk

Receiving Skill Behavior

When a skill detects _forwarded_from in its context:

1. Skip disk read of the forwarded artifact
2. Use the in-context content directly
3. Log: "Using forwarded content from {source} — skipped disk read of {path}"

Phase 3 Dispatch Chain (Optimized)

Step	Dispatch	Output	Forwarded to
3a	/ux audit {feature}	v2-audit-report	Step 3b (inline)
3b	/ux research {feature}	ux-research	Step 3c (inline)
3c	/ux spec {feature}	ux-spec	Steps 3d, 3e, 3f (inline)
3d	/ux validate {feature}	validation report	Step 3e (inline)
3e	/design audit	compliance report	Steps 3f, 3g (inline)
3f	/ux prompt {feature}	ux-build.md	disk only
3g	/design prompt {feature}	design-build.md	disk only

Each step writes to disk AND forwards inline. The receiving step skips its disk read.

Fallback: If result_forwarding config is missing or _forwarded_from is absent, the receiving skill reads from disk (v5.0 behavior).

Speculative Cache Pre-loading (v5.1 — Branch Prediction)

When a skill starts execution, speculatively pre-load the compressed cache views for the skill that is most likely to run next.

Protocol

1. On skill start, read skill-routing.json → speculative_preload.successor_map[current_skill]
2. If found and speculative_preload.enabled is true: a. Read likely_next and confidence from the successor entry b. If confidence >= 0.85: pre-load each cache entry in preload[] using compressed_view only c. Tag pre-loaded entries as _speculative: true
3. When the next skill actually starts: a. If it matches likely_next: the speculative entries become the warm cache (Phase 1 cache check is instant) b. If it does NOT match: discard speculative entries (cost: ~3K tokens, 1.5% of budget)

Misprediction Handling

• Misprediction cost is bounded at misprediction_budget_tokens (3,000 tokens)
• Only compressed_view fields are pre-loaded (never full cache entries)
• Prediction accuracy is tracked in change-log.json as speculative_prediction events
• If hit rate drops below hit_rate_target (0.85), the hub logs a warning and the user can disable speculative preloading

Successor Map Key Format

Keys use skill:command format for sub-command-level prediction, or just skill for skill-level prediction:

• ux:spec → predicts design:audit (Phase 3 chain)
• dev → predicts qa (implementation → testing)

Fallback: If speculative_preload config is missing, no pre-loading occurs (v5.0 behavior).

Systolic Chain Protocol (v5.1 — TPU Systolic Array)

For defined multi-skill chains, execute in pipeline mode: each skill receives ONLY upstream output + its own L1 cache. No global shared-layer reads mid-execution.

When to Use

Check skill-routing.json → systolic_chains.defined_chains for a matching chain based on the current phase and work type:

• v2_refactor_pipeline: Phase 3 for v2 refactor work subtypes
• new_feature_ux_pipeline: Phase 3 for new UI features
• implementation_pipeline: Phase 4 → Phase 5

Full Isolation Mode

For chains with isolation_level: "full" (UX/design pipelines):

1. Chain start: Hub identifies the matching chain and loads the first stage's inputs
2. Per stage: a. Skill receives ONLY items listed in its receives[] (from upstream output or initial inputs) b. Skill has access to its own L1 cache (compressed_view only) c. Skill does NOT read from shared layer (.claude/shared/*.json) d. Skill produces its produces artifact e. Output is forwarded inline to the next stage (per Result Forwarding protocol)
3. Chain end: After ALL stages complete: a. All artifacts are batch-written to disk b. Shared layer is updated with all accumulated state changes c. state.json transitions are recorded

Partial Isolation Mode

For chains with isolation_level: "partial" (implementation pipeline):

1. Each stage receives upstream output + L1 cache (same as full)
2. Each stage MAY read from shared layer when reads_global: true is set for that stage
3. Write-back happens after each stage (not batched)

Isolation Guarantee

The key invariant: in full isolation, the shared layer is NEVER read between chain start and chain end. This means:

• No Amdahl's Law bottleneck on the shared-layer read path
• Each stage's context window contains only what it needs
• The shared layer is a write-back target, like a register file in hardware

Fallback: If no matching chain exists in systolic_chains.defined_chains, use standard per-skill execution with shared-layer reads (v5.0 behavior).

Alternative invocation: /pm-workflow roadmap <verb>

When $ARGUMENTS is the literal token roadmap (optionally followed by a verb), do NOT run the standard feature lifecycle. Instead load the roadmap reference and dispatch to the requested verb:

Invocation	What it does
/pm-workflow roadmap (no verb)	Print verb menu + brief usage
/pm-workflow roadmap review	Read current roadmap + state.json drift report
/pm-workflow roadmap prioritize	Re-rank backlog via RICE / MoSCoW / Now-Next-Later
/pm-workflow roadmap decide {item}	Produce a decision memo for one backlog item

Dispatch: load .claude/skills/pm-workflow/references/roadmap.md (Anthropic progressive-disclosure pattern). Follow the sub-command protocol section that matches the verb. Do not load any phase-lifecycle protocols (Setup, State Initialization, Work Item Type Selection, Phase 0–9) when in roadmap mode — those are for feature work.

Outputs go to:

• Decision memos: docs/master-plan/decisions/YYYY-MM-DD-<slug>.md
• Reordering diffs: stdout (user applies manually)
• State drift report: stdout

Closes §3A Gap #2 from docs/skills/skills-review-2026-05-13.md.

---

Setup

1. Check if .claude/features/$0/state.json exists

   • If yes: resume from current_phase
   • If no: create the directory and initialize state.json from the schema below

2. Write the active-feature lockfile (v7.8 Mechanism C wiring): write $0 to .claude/active-feature. The PostToolUse:Read hook (scripts/observe-cache-hit.py) reads this file to attribute auto-collected cache events to the correct feature in .claude/logs/_session-<id>.events.jsonl. Without it, session events accumulate with empty active_feature strings and the v7.9 attribution-based gates won't see them.

   echo "$0" > .claude/active-feature
   

3. Read the current state and announce: "Feature $0 — currently in Phase {N}: {name}. Here's what needs to happen next."

4. GitHub Issue sync check:

   • If github_issue_number is set in state.json: verify the issue exists and check its phase:* label
   • If no github_issue_number: search GitHub Issues for this feature by title. If found, store the number. If not found, offer to create one.
   • If state.json current_phase doesn't match the GitHub Issue's phase:* label: ask the user which source is correct and reconcile (see Conflict Resolution in Dashboard Sync Automation)

5. If the user says "Move to {phase}" or "Roll back to {phase}": execute the Manual Override procedure (see Dashboard Sync Automation) instead of the normal phase workflow.

State Initialization

Create .claude/features/$0/state.json:

{
  "feature": "$0",
  "created": "{current ISO-8601 timestamp}",
  "updated": "{current ISO-8601 timestamp}",
  "branch": "feature/$0",
  "current_phase": "research",
  "work_type": "feature",
  "has_ui": null,
  "requires_analytics": null,
  "phases": {
    "research": { "status": "in_progress", "approved_at": null, "sources": [] },
    "prd": { "status": "pending", "approved_at": null, "analytics_spec_complete": false },
    "tasks": { "status": "pending", "count": 0 },
    "ux_or_integration": { "status": "pending", "type": null, "preflight_passed": null },
    "implementation": { "status": "pending", "commits": [] },
    "testing": { "status": "pending", "ci_passed": false, "tests_added": 0, "instrumentation_verified": false, "analytics_tests_added": 0, "analytics_verification_passed": false },
    "review": { "status": "pending", "risks": [], "ci_main": false, "ci_feature": false },
    "merge": { "status": "pending", "pr_number": null, "analytics_regression_passed": null },
    "documentation": { "status": "pending" },
    "metrics": {
      "primary": { "name": "", "baseline": null, "target": null, "current": null },
      "secondary": [],
      "guardrails": [],
      "instrumentation_ready": false,
      "first_review_date": null,
      "kill_criteria": ""
    }
  },
  "tasks": [],
  "figma_node_ids": {},
  "figma_build_status": null,
  "pre_merge_review": { "ux": null, "design": null }
}

Field reference (v4.X additions, 2026-05-06):

• phases.ux_or_integration.preflight_passed — set by /ux preflight + /design preflight aggregate result. true when both gates pass; false if any P0 unresolved.
• figma_node_ids — populated by /design build. Keys are screen names from ux-spec.md, values are Figma node IDs (e.g. {"imported_plans_list": "1234:567"}). Read by /design pre-merge-review.
• figma_build_status — "completed" (MCP build succeeded), "deferred_to_prompt" (MCP unreachable, prompt saved for manual handoff), or null (not yet attempted).
• pre_merge_review.ux — "passed" | "passed_with_notes" | "blocked" | null. Set by /ux pre-merge-review. Phase 7 gate.
• pre_merge_review.design — "passed" | "passed_with_notes" | "blocked" | null. Set by /design pre-merge-review. Phase 7 gate.

---

Work Item Type Selection

Before starting Phase 0, determine the work item type:

Ask: "Is this a Feature, Enhancement, Fix, or Chore?"

Type	Phases	When to Use
Feature	Full 10-phase lifecycle (0-9)	New capabilities, new screens, new services
Enhancement	Tasks → Implement → Test → Merge (4 phases)	Improvements to shipped features with existing PRDs
Fix	Implement → Test (2 phases)	Bug fixes, error handling, security patches
Chore	Implement only (1 phase)	Docs, config, refactoring, dependency updates

Set work_type in state.json. For non-Feature types:

• Enhancement: Skip Research, PRD, UX. Start at Phase 2 (Tasks). Set parent_feature to the existing feature being enhanced.
• Fix: Skip to Phase 4 (Implement). Auto-set first task with skill: "dev". Test + Review are still required (Phase 5 + 6).
• Chore: Skip to Phase 4 (Implement). Test gate is optional, but review gate is still required for any code change.

All skipped phases get status: "skipped" with reason: "work_type:{type}" in the audit trail.

Review Gates (Non-Negotiable)

Every work item type that changes code MUST pass through Test + Review before merge. The fast-track reduces planning overhead, not quality gates:

Type	Planning	Test	Review	Merge	Feedback
Feature	Full	Required	Required	Required	Full loop
Enhancement	Partial	Required	Required	Required	Full loop
Fix	None	Required	Required	Required	Full loop
Chore (docs only)	None	Optional	Required	Required	Notify only

Change Broadcast (Awareness Protocol)

When ANY work item completes (merge to main), broadcast a change notification to ALL skills so the entire system stays aware:

1. Update .claude/shared/feature-registry.json — record what changed, when, and why
2. Notify downstream skills:
   • /qa — "New code merged. Run regression check on next cycle."
   • /cx — "Change shipped: {description}. Monitor user feedback for impact."
   • /analytics — "Verify instrumentation still intact after merge."
   • /ops — "Deployment pending. Check health after deploy."
   • /design — "If UI changed, verify design system compliance."
   • Notion — Update the feature's Notion page to phase:done via notion-update-page.
3. Write a change event to .claude/shared/change-log.json:

   {
     "timestamp": "ISO-8601",
     "feature": "feature-name",
     "work_type": "fix",
     "description": "Eliminated force unwraps in production code",
     "files_changed": 4,
     "skills_notified": ["qa", "cx", "ops"],
     "review_status": "approved",
     "test_status": "passed"
   }
   

Upstream Feedback Loop

When /cx analyze or /qa regression detects an issue post-merge:

1. Classify the signal:

   • Customer confusion → /marketing (messaging) + /design (UX)
   • Regression → /dev (fix) + /qa (test gap)
   • Performance degradation → /ops (infra) + /dev (optimization)
   • Expectation mismatch → /pm-workflow (re-scope)

2. Create a new work item (typically Fix or Enhancement) that links back to the original change

3. The new work item inherits context from the original — no information is lost

4. Close the loop: When the fix ships, /cx re-monitors to verify the issue is resolved

---

Phase 0: Research & Discovery

Goal: Understand what we're building, why, and validate the approach before committing to a PRD.

Phase 0.0 — Unified preflight (v7.8.6+, MANDATORY first step)

Before any phase-specific work, run:

make preflight WORK_TYPE=<feature|enhancement|fix|chore> [FEATURE=<name>]

This writes .claude/shared/preflight-cache.json with the data downstream skills depend on:

• W1 ssh-agent state — prevents silent commit-signing hang
• PR citation cache freshness — prevents v7.8.4 PR_CACHE_STALE false-positives
• Current branch + isolation status — flags infra-path commits from main
• Current integrity findings + advisory count — system-wide health
• Integrity diff vs 2026-05-14 anchor — drift detection (closes 96h cron gap per data-integrity §2.1)
• Documentation-debt + measurement-adoption baselines — calibration data for post-ship comparison
• Work-type-specific check — feature state.json, enhancement parent, fix high-risk-touch, chore infra-path

Downstream skills (/ux, /design, /dev, /qa, /analytics, /cx, /ops, /release, /marketing, /research) read this cache instead of re-collecting the data. The cache is overwritten each run; re-run when work_type or feature changes.

Block phase advancement if the preflight reports blocking > 0.

Cross-layer freshness (auto-chained, 2026-05-28+). make preflight also runs make freshness-check which surfaces:

• Recent merged PRs (both repos, last 7d) — catches the W20 failure mode where session-state thinks work is open but the operator already shipped it (root-cause of the 2026-05-28 prereg-duplication incident).
• Stale worktrees (behind > 7 commits vs origin/main) — flags worktrees that would silently overwrite shipped work on commit.
• Memory ↔ feature-state drift — surfaces MEMORY.md entries claiming "in flight" / "paused" / "pending" for features whose state.json::current_phase is now complete.
• Linear sync (optional) — FIT-team root-issue status when LINEAR_API_KEY is set.

Cross-reference the freshness output against any operator-gate inventory, status survey, or files you're about to edit. See W20 + feedback_cross_layer_freshness_check.md.

Phase 0.1 — Per-feature reality-check (v7.9.1+ F2, MANDATORY for Enhancement / Fix / Chore)

After Phase 0.0 preflight, run the per-feature reality-check:

make phase-0-reality-check FEATURE=<feature-name>
# or equivalently:
python3 scripts/phase-0-reality-check.py --feature <feature-name>

This reads the feature's state.json::tasks list and cross-checks each pending / in_progress / open task against the last 30 days of:

• Git log subjects — has anyone shipped a commit whose subject contains the task's keywords?
• Merged PR titles (FT2 + fitme-story) — has either repo merged a PR matching the task?
• Tier 2.2 log events in .claude/logs/<feature>.log.json — has anyone logged an implementation or phase_transition event mentioning the task ID or keywords?

Output: stdout summary + structured JSON at .claude/shared/phase-0-reality-check.json. Advisories surface as "this task may already be done" — never blocking, always operator-judgment.

Why this matters. I (the agent + operator) repeatedly hit the post-squash-merge state-drift pattern in 2026-06-01 → 2026-06-04: 5 confirmed instances where state.json::tasks said pending but the file changes were already on main via a prior PR. Phase 0.1 surfaces this BEFORE the new work gets scheduled, so the task list gets reconciled first (likely via make close-feature FEATURE=<name>) and the new Phase 0 starts against accurate state.

When this is mandatory: for any Enhancement, Fix, or Chore where the parent feature exists. Optional but recommended: new Feature work where the topic intersects with recent shipped work — false positives are fine since they cost nothing to dismiss.

Block phase advancement if Phase 0.1 flags ≥1 advisory AND the operator has not explicitly acknowledged the finding (via state.json::phase_0_reality_check_acknowledged: ["T3 reviewed — not the same scope"] or by flipping the affected task's status).

Spec: docs/master-plan/infra-master-plan-2026-05-12.md §3.1 Theme A F2 (RICE 42.7).

Phase 0 variant by work subtype

Subtype	Phase 0 primary output	Skills dispatched
New feature	research.md (market + competitive + alternatives) + populated state.json::brainstorm block	/brainstorm-pm (default — problem/solution/assumption/strategy modes + three-option trade-off mode for scoped problems with multiple viable paths, added 2026-06-03) → /research wide → /research narrow → /research feature
V2 refactor (state.json.work_subtype == "v2_refactor")	v2-audit-report.md (numbered findings against ux-foundations.md, each with P0/P1/P2 severity + tractability tag: auto / decision / new-token / new-component)	/ux audit on the v1 file
Enhancement	Skipped — parent feature's research already exists	—
Fix / Chore	Skipped	—

For v2 refactors, the research phase is an audit phase, not a market-research phase. The output drives the rest of the lifecycle: every finding becomes a Phase 2 task, every P0/P1 finding becomes a required Phase 4 patch, and Section A of docs/design-system/v2-refactor-checklist.md is the completion gate.

New-feature brainstorm preflight (v7.8.5+)

Before filling out the research template, run /brainstorm-pm to lock the problem framing, surface assumptions, and enumerate alternative solutions. The skill writes to state.json::brainstorm.<mode> which serves as input to Phase 1 PRD sections (see .claude/skills/brainstorm-pm/SKILL.md → §"Integration with /pm-workflow"). Skip only if the problem framing is already documented in a research/spec doc and validated externally.

Three-option trade-off mode (added 2026-06-03): when the problem is locked + scope is roughly known but the implementation path isn't, run /brainstorm-pm three-option to produce a UX / Design / Dev trade-off matrix across ≥3 distinct paths spanning the feasibility space. NO pre-ranking — output IS the matrix and the user picks. Matrix lands at state.json::brainstorm.three_option_matrix and renders as the PRD's §Alternatives considered section.

Three-option auto-dispatch heuristic (added 2026-06-03)

Phase 0 auto-invokes /brainstorm-pm three-option after the 4-base-mode brainstorm pass completes, when the problem-shape signals are ambiguous. Decision tree the agent evaluates:

If state.json::brainstorm.problem_statement is set AND
   state.json::brainstorm.solution_alternatives.length ≥ 2:

   Skip three-option — solution mode already produced ranked candidates.

Else if work_type ∈ {feature, enhancement, refactor_v2} AND
        problem statement contains ≥1 of:
          • "could be A or B", "vs", "trade-off", "trade off", "alternative"
          • "implement", "build", "wire" + ≥2 distinct platform/surface terms
            (e.g. "iOS and Web", "in-app + cloud", "sync vs async")
          • backlog row has "alternatives considered" in scope
        OR the operator explicitly requests it ("/pm-workflow {name} --mode=three-option"):

   AUTO-INVOKE `/brainstorm-pm three-option`. Surface the matrix to the operator
   inline; require explicit pick before advancing to Phase 1.

Else if work_type == fix OR chore:
   DO NOT auto-invoke. (Three-option matrices have negative ROI on bug fixes —
   the answer is "fix the root cause" not "pick a trade-off".)

Otherwise:
   DEFAULT NO. The 4 base modes are enough; offer three-option as an explicit
   command (`/brainstorm-pm three-option`) without auto-dispatching.

Fallback when heuristic mis-fires (matrix becomes ritual rather than discriminating): the operator can disable auto-dispatch for the current session via /pm-workflow {feature} --no-three-option. Record the disable in state.json::brainstorm.three_option_skip_reason so the kill-criterion metric (per brainstorm-pm/SKILL.md Three-Option mode §Kill criterion) can measure how often the operator overrides the heuristic. If override rate exceeds 30% over a 30-day rolling window, the gate condition fires: narrow the heuristic to require explicit operator opt-in instead of auto-dispatch.

Telemetry: Phase 0 emits one event per dispatch decision to gate-coverage.jsonl with key pm_workflow.three_option_auto_dispatch and outcome ∈ {invoked, skipped_solution_already_done, skipped_fix_chore, skipped_default_no, operator_disabled, operator_explicit_request}. The existing weekly framework-status cron tracks this alongside other gates.

New-feature research template

Create .claude/features/$0/research.md using the research template. Fill in:

1. What is this solution? — Plain-language description
2. Why this approach? — Problem it solves, user pain points addressed
3. Why this over alternatives? — Research 2-3 alternative approaches. Create a comparison table:

   Approach	Pros	Cons	Effort	Chosen?

4. External sources — Search for relevant articles, documentation, APIs, libraries. Include links.
5. Market examples — How do competitors or other apps solve this? Include app names and what they do well/poorly.
6. If this feature has UI:
   • Search for design inspiration — find 3-5 examples of similar UI patterns you'd recommend
   • Document design solutions that could work (with reasoning)
   • Note visual references and mood (colors, layout patterns, interaction models)
   • Link to any Figma exploration
7. Data & demand signals — What data justifies building this? (user feedback, analytics, market size, support requests)
8. Technical feasibility — Dependencies, risks, unknowns, platform constraints
9. Proposed success metrics — Draft the primary metric and 2-3 secondary metrics
10. Decision — Recommended approach with rationale

Present the research to the user and ask for approval. On approval, execute the Phase Transition Procedure (see Dashboard Sync Automation).

---

Phase 1: PRD

Goal: Define exactly what we're building with measurable success criteria.

Create .claude/features/$0/prd.md using the PRD template (see prd-template.md). Every field is mandatory.

Critical: The success metrics section is NON-NEGOTIABLE. No PRD is approved without:

• Primary metric with baseline and target
• Secondary metrics (2-3)
• Guardrail metrics (things that must not degrade)
• Leading indicators (measurable within 1 week)
• Lagging indicators (30/60/90 day impact)
• Instrumentation plan (how we measure)
• Review cadence
• Kill criteria

Ask the user: "Does this feature have a UI component?" → Set has_ui in state.json.

Ask the user: "Does this feature introduce new measurable interactions (screens, user actions, badges, achievements)?" → Set requires_analytics in state.json.

Analytics Spec Gate (if requires_analytics = true)

Before the PRD can be approved, define and validate the GA4 analytics instrumentation for this feature:

1. Read existing taxonomy — Read FitTracker/Services/Analytics/AnalyticsProvider.swift (all enums: AnalyticsEvent, AnalyticsParam, AnalyticsScreen, AnalyticsUserProperty) and docs/product/analytics-taxonomy.csv to understand the current event landscape.

2. Draft Analytics Spec — For each measurable action in the PRD, fill in the "Analytics Spec (GA4 Event Definitions)" section of the PRD template:

   • New events (name, category, GA4 type, trigger screen, parameters, conversion flag)
   • New parameters (name, type, allowed values, which events use them)
   • New screens (snake_case name, SwiftUI view class, category)
   • New user properties (if any — remember max 25 total custom)

3. Validate naming conventions against GA4 rules documented in AnalyticsProvider.swift:

   • snake_case format, lowercase only
   • Max 40 characters for event and parameter names
   • No reserved prefixes (ga_, firebase_, google_)
   • No duplicate names against existing enums in AnalyticsProvider.swift
   • No PII in any parameter (no emails, names, phone numbers, user IDs)
   • Parameter values max 100 characters
   • Max 25 parameters per event
   • Total custom user properties still ≤25 after additions
   • Use GA4 recommended events where available (login, sign_up, share, select_content, tutorial_begin, tutorial_complete)

4. Complete the Naming Validation Checklist in the PRD (all boxes must be checked).

5. Update state.json: Set phases.prd.analytics_spec_complete = true.

The PRD is NOT approvable until the Analytics Spec passes validation (when requires_analytics = true). If requires_analytics = false, the Analytics Spec section is skipped.

Present the PRD and ask for approval. On approval, execute the Phase Transition Procedure.

---

Phase 2: Task Breakdown

Goal: Divide the PRD into implementable subtasks.

Create .claude/features/$0/tasks.md with:

1. Read the approved PRD
2. Break into subtasks, each with: title, description, estimated effort, dependencies
3. Classify each task: ui, backend, data, test, docs, infra
4. Order by dependency graph
5. Estimate total effort
6. Assign each task a skill from: dev, qa, design, analytics, ops, marketing, cx, research, release
7. Identify task dependencies — which tasks must complete before others can start
8. Estimate effort in days for each task

Structured Task State: After creating tasks.md, also write the tasks to state.json.tasks[]:

{
  "tasks": [
    {
      "id": "T1",
      "title": "Task title from tasks.md",
      "type": "ui|backend|analytics|test|design|docs|infra|research|marketing",
      "skill": "dev|qa|design|analytics|ops|marketing|cx|research|release",
      "status": "pending",
      "priority": "critical|high|medium|low",
      "effort_days": 0.5,
      "depends_on": [],
      "completed_at": null
    }
  ]
}

Task status lifecycle: pending → ready (all depends_on are done) → in_progress → done

If a task's dependencies cannot be met, set status to blocked.

Present task list and ask for approval. On approval, execute the Phase Transition Procedure.

---

Phase 3: UX/UI Definition (if has_ui = true)

Goal: Define screens, components, and design requirements before coding — grounded in UX research and validated against the design system. The hub dispatches /ux and /design sub-commands in sequence, collects their artifacts, and presents the whole package for user approval before advancing.

Phase 3 dispatch chain

Step	Skill dispatch	Output	Gate
3a	/ux audit {feature} (v2 refactor only)	.claude/features/{f}/v2-audit-report.md	User reviews audit findings
3b	/ux research {feature}	.claude/features/{f}/ux-research.md	Principles identified
3c	/ux spec {feature}	.claude/features/{f}/ux-spec.md	Spec covers all 5 states + a11y + principles
3d	/ux validate {feature}	heuristic validation report in chat	No unresolved P0 violations
3e	/ux preflight {feature} (v4.X — NEW)	.claude/features/{f}/ux-preflight-audit-{date}.md + .claude/cache/_shared/ux-spec-preflight.json entry	P0 unresolved → spec NOT approvable
3f	/design preflight {feature} (v4.X — NEW)	.claude/features/{f}/design-preflight-{date}.md + .claude/shared/figma-bridge-status.json	DS P0=0; Figma MCP liveness recorded; library accessibility recorded
3g	/design audit on the ux-spec	compliance report	Token, component, pattern, a11y, motion all pass
3h	/ux prompt {feature}	docs/prompts/ux/{date}-{f}-ux-build.md	Handoff prompt ready
3i	/design prompt {feature}	docs/prompts/ui/{date}-{f}-design-build.md	Handoff prompt ready
3j	/design build {feature} (v4.X — auto-dispatched)	Figma screens (or saved prompt fallback) + state.json.figma_node_ids populated + row added to

Steps 3a-3d produce the spec; steps 3e-3f are the v4.X preflight gates that prevent silent-pass errors (token/component/pattern existence + Figma MCP liveness); step 3g validates against the design system; steps 3h-3i produce the auto-generated build prompts; step 3j auto-builds Figma frames (or saves a portable prompt for manual handoff if MCP is down). UX prompts land in docs/prompts/ux/, design/UI prompts land in docs/prompts/ui/. Legacy flat files migrated to docs/prompts/_legacy/.

v2 refactor note: For state.json.work_subtype == "v2_refactor", step 3a is non-skippable and its output drives steps 3b-3d. For new_ui, step 3a is skipped (no v1 to audit) and step 3b starts from the PRD.

Why steps 3e + 3f exist (added v4.X, 2026-05-06): During the import-training-plan resume, the v2 ux-spec.md was drafted referencing 4 tokens/components that didn't exist in the codebase (AppRadius.pill, AppMotion.standardEase, SettingsActionLabel with custom badge slot, toast component). The user-ordered pre-Phase-4 audit caught all 4 before code was written; without it, Phase 4 would have hit "no such symbol" errors. Steps 3e + 3f are that audit promoted from manual-on-request to a mechanical gate.

Why step 3j exists (added v4.X): Smart Reminders shipped 2026-04-29 with code-first; Figma followed manually. Push Notifications still pending Figma weeks later. Import-Training-Plan was missed entirely until the user flagged it post-Phase-5. Auto-dispatching /design build ensures Figma sync happens in Phase 3 (or is explicitly deferred with a written prompt) so Phase 6 (/design pre-merge-review) has ground truth.

V1 vs V2 — refactor or new feature?

Before starting Phase 3, classify the work:

Classification	Trigger	Phase 3 expectation	Phase 4 file convention
New UI feature	No existing v1 file for this surface	Phase 3 is non-skippable. Must produce ux-spec.md and pass the design system compliance gateway before any view code is written.	Single Swift file at the canonical path (e.g. Views/Home/HomeView.swift). Bottom-up from foundations.
V2 refactor (UX Foundations alignment)	An existing v1 Swift file for this surface needs alignment with ux-foundations.md	Phase 3 starts with a v2-audit-report.md walking the existing v1 file against ux-foundations.md, THEN produces ux-spec.md for the v2 file.	New file at {originalDir}/v2/{SameFileName}.swift. v1 file is not patched in place — it stays as a historical reference per the V2 Rule in CLAUDE.md. project.pbxproj is updated in the same commit that creates the v2 file: v2 added to Sources, v1 removed from Sources but kept as a PBXFileReference.

Set state.json.work_subtype to either "new_ui" or "v2_refactor". For v2_refactor, populate state.json.v2_file_path with the planned v2 file path (using the v2/ subdirectory convention) before Phase 3 advances.

Phase 3 also requires the design system v2 refactor checklist (docs/design-system/v2-refactor-checklist.md) to be referenced in ux-spec.md. Each checkbox the spec touches must be addressed in Phase 4.

Step 1: UX Research & Principles (dispatches /ux research)

For v2 refactors, dispatch /ux audit first to produce .claude/features/$0/v2-audit-report.md as the gap-analysis driver. Then dispatch /ux research $0 to consolidate the audit findings into applicable UX principles. For new UI features, go straight to /ux research $0.

Before designing screens, research and document UX best practices relevant to this feature:

1. UX principles applicable to this feature — identify which core principles apply:

   • Fitts's Law (target size and distance for tap targets)
   • Hick's Law (minimize choices per screen)
   • Jakob's Law (users expect your app to work like others they know)
   • Progressive disclosure (show only what's needed at each step)
   • Recognition over recall (visible options vs memorized commands)
   • Consistency (internal consistency with FitMe, external with iOS conventions)
   • Feedback (every action gets a response)
   • Error prevention (design to prevent mistakes, not just handle them)

2. iOS Human Interface Guidelines — check Apple's HIG for relevant patterns:

   • Navigation patterns (push, modal, tab, sheet)
   • Input patterns (forms, pickers, steppers, sliders)
   • Feedback patterns (haptics, animations, alerts)
   • Accessibility requirements (Dynamic Type, VoiceOver, minimum tap targets 44pt)

3. UX best practices for this feature type — search for research and articles on the specific interaction pattern (e.g., "best practices for food logging UX", "training timer UI patterns")

4. Document findings in .claude/features/$0/ux-research.md:

   • Applicable principles and how they apply
   • iOS HIG references
   • External UX research sources with links
   • Recommended patterns based on research

Step 2: Design Definition

Follow the Feature Development Gateway at docs/design-system/feature-development-gateway.md:

1. Problem framing (already done in PRD)
2. Behavior definition: entry points, primary task flow, edge cases, states (empty/loading/error/success)
3. Screen list with wireframe descriptions
4. Component inventory (reuse existing AppComponents where possible — check FitTracker/DesignSystem/AppComponents.swift)
5. Design token requirements (map to existing AppTheme.swift tokens; flag any new primitives needed)
6. User interaction flows
7. Accessibility requirements (informed by UX research from Step 1)
8. Reference the design inspiration from Phase 0 research
9. Reference the UX principles from Step 1 — explain HOW each principle influenced the design

Also walk through docs/design-system/feature-design-checklist.md for every UI decision.

Create .claude/features/$0/ux-spec.md with the above.

Step 3: Design System Compliance Gateway

Before approval, validate the design against the design system.

Run a compliance check on the UX spec:

1. Token compliance — Every color, font, spacing, and radius value maps to an existing semantic token in AppTheme.swift. Flag any raw/hardcoded values.
2. Component reuse — Every UI element maps to an existing component in AppComponents.swift or has a documented reason for a new component.
3. Pattern consistency — Navigation, layout, and interaction patterns are consistent with existing screens (check docs/design-system/component-contracts.md).
4. Accessibility compliance — Minimum 44pt tap targets, WCAG AA contrast (4.5:1 text), Dynamic Type support, VoiceOver labels defined.
5. Motion compliance — Animations use AppMotion presets, reduce-motion support via MotionSafe modifier.

Generate a compliance report:

Check	Status	Details
Token compliance	Pass/Fail	{list any violations}
Component reuse	Pass/Fail	{new components needed?}
Pattern consistency	Pass/Fail	{deviations from existing patterns}
Accessibility	Pass/Fail	{issues found}
Motion	Pass/Fail	{non-standard animations?}

If all checks pass: Present the UX spec for approval.

If any checks fail: Alert the user with the compliance report and present three options:

Design System Compliance Alert

The UX spec has {N} design system violations: {list violations}

Since this feature is on its own branch, you have full flexibility:

1. Fix violations — Update the UX spec to comply with the current design system
2. Evolve the design system — The design system is a living framework. If these changes improve it, update the tokens/components as part of this feature. Document the evolution in docs/design-system/feature-memory.md
3. Override with justification — Proceed with the violations, documenting why the design system doesn't apply here (edge case, experimental, etc.)

The design system should serve the product, not constrain it. Choose the path that makes the best product.

Record the user's decision in state.json under ux_or_integration.compliance_decision.

Design system evolution rules:

• New tokens/components proposed by a feature are added on the feature branch
• They are reviewed alongside the feature code in Phase 6
• If approved, they become part of the design system when the feature merges to main
• Update docs/design-system/feature-memory.md with what changed and why
• Run make tokens-check to verify token pipeline still passes

Step 4: Generate handoff prompts (auto)

Once steps 1-3 are approved (ux-research.md, ux-spec.md, compliance gateway passed), dispatch both prompt-writer sub-commands in parallel:

/ux prompt $0       → writes docs/prompts/{YYYY-MM-DD}-$0-ux-build.md
/design prompt $0   → writes docs/prompts/{YYYY-MM-DD}-$0-design-build.md

Both prompts are ready to hand off to downstream agents (Figma MCP, SwiftUI implementation agent, etc.). The /ux prompt carries the what-and-why; the /design prompt carries the how-it-looks. Matching filename prefixes so the two can be read together.

Verify both prompt files were written before marking Phase 3 as approvable. If either file is missing, re-run the corresponding sub-command.

Present UX spec + compliance report + both handoff prompts, and ask for approval. On approval, execute the Phase Transition Procedure.

Phase 3b: Integration Requirements (if has_ui = false)

Goal: Define technical contracts and integration points.

Create .claude/features/$0/integration-spec.md with:

1. API contracts (endpoints, payloads, auth)
2. Data model changes (new models, migrations)
3. Service dependencies
4. Error handling strategy
5. Backward compatibility plan

Present spec and ask for approval. On approval, execute the Phase Transition Procedure.

---

Phase 4: Branch & Implement

Goal: Write the code on an isolated branch.

1. Create branch: git checkout -b feature/$0 main

V2 Refactor — file convention (per CLAUDE.md V2 Rule)

If state.json.work_subtype == "v2_refactor":

1. Do not modify the v1 file in place. v1 stays read-only during the refactor. The audit (v2-audit-report.md from Phase 3) is the gap analysis; the v2 file is built bottom-up from the design system foundations.

2. Create the v2 file in a v2/ subdirectory next to v1, keeping the original file name. Path is state.json.v2_file_path and follows the pattern {originalDir}/v2/{SameFileName}.swift. Both files define the same Swift type — only the directory differs.

3. Update FitTracker.xcodeproj/project.pbxproj in the same commit:

   • Add a new PBXGroup for the v2/ directory under the parent group
   • Add a PBXFileReference for the new v2 file under that PBXGroup
   • Add a PBXBuildFile entry referencing the new v2 file
   • Add the new PBXBuildFile to the Sources build phase
   • Remove the v1 file's PBXBuildFile from the Sources build phase (the v1 PBXFileReference and group entry stay so the file shows in the navigator and git diffs cleanly)

4. Mark v1 as historical with a header comment when v2 is functionally complete:

   // HISTORICAL — superseded by v2/{ScreenName}.swift on {date} per
   // UX Foundations alignment pass. See
   // .claude/features/{name}/v2-audit-report.md for the gap analysis.
   // This file is no longer in the build target; it stays in the repo
   // as a reviewable reference for the v1 → v2 diff.
   

5. Parent views need no call-site changes. Both v1 and v2 declare the same Swift type (e.g. MainScreenView) — RootTabView keeps writing MainScreenView() but the symbol now resolves to the v2 file because v1 is no longer in Sources. The swap happens entirely in project.pbxproj.

6. Walk the v2 refactor checklist at docs/design-system/v2-refactor-checklist.md before requesting Phase 5 (Test) approval. Set state.json.phases.implementation.checklist_completed = true when all applicable boxes are ticked.

Task Complexity Classifier (v5.1 — ARM big.LITTLE)

Before dispatching ready tasks, classify each one as lightweight (E-core, parallel lane) or heavyweight (P-core, serial lane). This ensures small/simple tasks don't block behind large/complex ones, and heavyweight tasks get full dedicated attention.

Classification Protocol

1. Compute the ready set — tasks where ALL entries in depends_on have status done

2. For each ready task, score heavyweight indicators from skill-routing.json → task_complexity_gate.classification:

   Indicator	Weight	How to detect
   files_changed_gt_5	2	Task description mentions 5+ files, new screens, or broad refactor
   new_model_or_service	3	Task creates a new Swift model, service class, or manager
   token_budget_high	2	Task requires architecture decisions, research synthesis, or deep reasoning
   cross_feature_deps	2	Task's depends_on references tasks from a different feature
   requires_judgment	3	Task involves UX heuristic evaluation, risk assessment, or kill criteria review

3. Sum the weights of all matched heavyweight indicators

4. Classify:

   • Score >= 4 → Heavyweight (P-core, serial lane)
   • Score < 4 → Lightweight (E-core, parallel lane)

Quick Classification Examples

Task	Indicators matched	Score	Lane
"Add GA4 event for button tap"	files_changed ≤2, mechanical	0	E-core (parallel)
"Update analytics-taxonomy.csv"	config change, mechanical	0	E-core (parallel)
"Build new ProfileEditor screen"	new_model(3) + files>5(2) + judgment(3)	8	P-core (serial)
"Implement auth passkey flow"	new_service(3) + token_high(2) + cross_feature(2)	7	P-core (serial)
"Rename token AppColor.old → .new"	files ≤2, mechanical	0	E-core (parallel)
"Design ux-spec for new feature"	judgment(3) + token_high(2)	5	P-core (serial)

Lane Execution

After classification, present both lanes to the user and execute:

Phase 4 — Task Dispatch (big.LITTLE)

  E-core lane (parallel, sonnet):
    T3 (add GA4 event)    — score 0, lightweight
    T5 (update taxonomy)  — score 0, lightweight
    T7 (rename token)     — score 0, lightweight

  P-core lane (serial, opus):
    T1 (build ProfileEditor) — score 8, heavyweight
    T4 (auth passkey flow)   — score 7, heavyweight

  Blocked:
    T8 (unit tests) — needs T1, T4

1. Execute E-core lane first — all lightweight tasks in parallel (max 5 concurrent). Use model tier: sonnet. If multiple lightweight tasks match a batch_dispatch operation, batch them (Item 3 composition).
2. Then execute P-core lane — heavyweight tasks one at a time with full context. Use model tier: opus.
3. On each task completion — recompute ready set, re-classify newly unblocked tasks, add to appropriate lane.
4. Phase 4 is complete when ALL tasks (both lanes) have status done.

Composition with Other v5.1 Items

• Item 5 (Model Tiering): E-core lane → sonnet, P-core lane → opus (overrides phase-level tier)
• Item 3 (Batch Dispatch): Multiple E-core tasks targeting the same skill can batch (e.g., 3 analytics taxonomy updates → single batch)
• Item 4 (Result Forwarding): P-core tasks in a chain forward results inline
• Item 7 (Systolic Chains): P-core tasks that match a defined chain execute in systolic mode

Fallback: If task_complexity_gate is missing or enabled is false, skip classification and use the standard parallel dispatch below (v5.1 behavior).

Parallel Task Dispatch (Legacy — used when complexity gate is disabled)

When the Task Complexity Classifier above is disabled or missing, Phase 4 falls back to dependency-aware parallel execution without lane separation:

1. Compute the ready set — tasks where ALL entries in depends_on have status done
2. Group by skill — organize ready tasks by their skill field
3. Present to user:

   Ready to run in parallel:
     /dev:       T1 (container view), T2 (welcome screen), T3 (goals screen)
     /design:    T9 (progress bar component)
   Blocked (waiting on dependencies):
     /analytics: T8 (GA4 events) — needs T1, T2
     /qa:        T10 (unit tests) — needs T1-T9
   

4. Execute ready tasks — work on ready tasks, potentially across skills
5. On each task completion:
   • Set task status: "done" and completed_at: timestamp
   • Recompute the ready set (completed task may unblock others)
   • Present newly unblocked tasks
6. Rebuild cross-feature queue — update .claude/shared/task-queue.json
7. Phase 4 is complete when ALL tasks have status done

Cross-Feature Priority Queue

After any task state change, rebuild .claude/shared/task-queue.json:

{
  "version": "1.0",
  "updated": "{timestamp}",
  "queue": [
    {
      "feature": "feature-name",
      "task_id": "T1",
      "title": "Task title",
      "skill": "dev",
      "work_type": "feature",
      "priority_score": 8,
      "status": "ready",
      "effort_days": 0.5
    }
  ],
  "scoring": {
    "base": { "critical": 10, "high": 7, "medium": 4, "low": 1 },
    "work_type_boost": { "fix": 3, "enhancement": 1, "feature": 0, "chore": -1 }
  }
}

Priority score = base[priority] + work_type_boost[work_type]. Fixes automatically jump the queue.

2. Implement according to the approved task list
3. Commit incrementally with descriptive messages
4. Update state.json with commit hashes
5. Follow the branching rules:
   • Features touching >5 files OR adding new models/services → MUST use feature/{name} branch
   • Both the feature branch and main must remain CI-green

Present implementation summary and ask for approval. On approval, execute the Phase Transition Procedure.

---

Phase 5: Testing & Measurement

Goal: Verify the implementation works and metrics are instrumented.

1. Write unit tests for new functionality
2. Run the full CI suite: make tokens-check && xcodebuild build && xcodebuild test
3. Run regression check (existing tests still pass)
4. Verify metric instrumentation is in place — can we actually measure the success metrics defined in the PRD?
5. Record baseline values for all metrics before the feature is live
6. Update state.json: ci_passed, tests_added, instrumentation_verified

Analytics Verification (if requires_analytics = true)

After general tests pass, run dedicated analytics verification:

1. Unit test event firing — For each event defined in the PRD's Analytics Spec:

   • Create a test in FitTrackerTests/AnalyticsTests.swift (create the file if it doesn't exist — first feature bootstraps it)
   • Construct a MockAnalyticsAdapter and inject it via AnalyticsService(provider: mockAdapter, consent: consentManager)
   • Trigger the action that should fire the event
   • Assert mockAdapter.capturedEvents contains the event with the correct name
   • Assert all expected parameters are present with correct types and values
   • Assert no unexpected parameters leak through

2. Screen tracking verification — For each new screen in the Analytics Spec:

   • Call the screen tracking method (or trigger .analyticsScreen() modifier)
   • Assert mockAdapter.capturedScreens contains the expected screen name