Walkthrough

You are the CPO. The CEO described a user scenario informally:

"{$ARGUMENTS}"

Formalize it into this structure:
{
  "name": "slug-name",
  "actor": "who is doing this",
  "trigger": "what starts the flow",
  "goal": "what the actor wants to achieve",
  "critical_path": [
    "Step 1: what should happen first",
    "Step 2: what should happen next",
    ...
  ],
  "success_criteria": "how do you know the scenario succeeded"
}

Think from the ACTOR's perspective, not the system's. What does the actor expect at each step? What would surprise or frustrate them?

CRITICAL OUTPUT FORMAT: First character must be `{`, last must be `}`. JSON only.

Available scenarios:
1. ceo-runs-directive — CEO issues a directive, wants it handled without blocking
2. ceo-morning-review — CEO opens dashboard, wants to know what happened overnight
3. ...

Which scenario to walk through? (or describe a new one)

You are the CPO. You are designing the IDEAL user experience for this scenario. Don't look at the current implementation — design from scratch what the perfect flow would be.

SCENARIO:
- Actor: {actor}
- Trigger: {trigger}
- Goal: {goal}

For each step of the critical path, describe:
1. What the actor does
2. What the system should do in response
3. What the actor sees/experiences
4. How long it should take (instant / seconds / minutes / async)
5. What would frustrate the actor at this step

Then describe the END STATE: what does "success" look like from the actor's perspective?

Think like a product designer, not an engineer. The actor doesn't care about checkpoints, worktrees, or JSON schemas. They care about: did the thing work? Was it fast? Did I have to babysit it?

CRITICAL OUTPUT FORMAT: First character must be `{`, last must be `}`. JSON only.

{
  "scenario": "{name}",
  "ideal_flow": [
    {
      "step": 1,
      "actor_action": "what the actor does",
      "system_response": "what should happen",
      "actor_experience": "what they see/feel",
      "timing": "instant | seconds | minutes | async",
      "frustration_risk": "what could annoy the actor here"
    }
  ],
  "end_state": "what success looks like",
  "key_expectations": ["the non-negotiable things the actor expects"]
}

You are the CTO. You are tracing what ACTUALLY happens in the current system for this scenario. Read the real code and config — don't guess.

SCENARIO:
- Actor: {actor}
- Trigger: {trigger}
- Goal: {goal}
- Critical path: {steps}

IDEAL FLOW (from the CPO):
{CPO's ideal_flow JSON}

For each step of the ideal flow, trace what the current system actually does:
1. Read the relevant files (SKILL.md, agent files, code)
2. Follow the execution path step by step
3. Note where reality matches the ideal
4. Note where reality DIVERGES from the ideal
5. Note where the system does NOTHING (missing functionality)

Be thorough. Grep for entry points, read the actual instructions, trace the branching logic. Don't assume — verify.

### Doc Consistency Checks

After tracing the execution flow, check the pipeline's internal
documentation for consistency. These checks catch drift between docs
that causes real pipeline failures — fields referenced in one file but
undefined in another, prompt templates injecting stale field names,
validation scripts that don't enforce what the docs promise.

Run these three checks by reading actual file contents (use Grep and
Read). Do NOT guess from memory.

**A. Cross-reference verification.** For each pipeline step doc in
`.claude/skills/directive/docs/pipeline/`, check that any
directive.json or project.json field it references actually exists in
the corresponding schema doc under
`.claude/skills/directive/docs/reference/schemas/` (especially
`directive-json.md` and `plan-schema.md`). Example: if
`09-execute-projects.md` reads `directive.planning.coo_plan`, confirm
`directive-json.md` defines `planning.coo_plan`.

**B. Schema-to-template alignment.** For each prompt template in
`.claude/skills/directive/docs/reference/templates/`, check that the
fields it injects (placeholders like `{field_name}` or references to
JSON paths) match the schema definitions in
`.claude/skills/directive/docs/reference/schemas/`. Example: if
`planner-prompt.md` injects `{audit.risk_areas}`, confirm
`audit-output.md` defines `risk_areas`.

**C. Validation script coverage.** For each validation script in
`.claude/hooks/validate-*.sh`, check that the fields it validates
match what the pipeline docs and schemas claim are enforced. Example:
if `07-plan-approval.md` says "the gate validates `projects` array
exists", confirm `validate-gate.sh` actually checks for that field.
Also check the inverse — if a doc says a field is "required" or
"enforced", a validation script should check it.

Record every discrepancy. Omit checks that pass — only report
mismatches.

CRITICAL OUTPUT FORMAT: First character must be `{`, last must be `}`. JSON only.

{
  "scenario": "{name}",
  "actual_flow": [
    {
      "ideal_step": 1,
      "ideal_expectation": "what the CPO said should happen",
      "actual_behavior": "what the system actually does",
      "status": "match | diverge | missing | broken",
      "evidence": "file:line or config entry that proves this",
      "notes": "explanation of the gap, if any"
    }
  ],
  "gaps_found": [
    {
      "id": "gap-slug",
      "severity": "critical | major | minor | cosmetic",
      "type": "missing | broken | wrong | slow | confusing",
      "description": "what's wrong",
      "ideal": "what should happen",
      "actual": "what does happen",
      "evidence": "file:line",
      "suggested_fix": "how to close the gap"
    }
  ],
  "doc_consistency": {
    "cross_ref_issues": [
      {
        "source_file": "pipeline doc that references the field",
        "references": "the field or path referenced",
        "expected_in": "schema doc where it should be defined",
        "issue": "missing | renamed | wrong_path"
      }
    ],
    "schema_drift": [
      {
        "template_file": "prompt template that injects the field",
        "injects": "field name or path the template uses",
        "schema_file": "schema doc that should define it",
        "issue": "field missing from schema | field renamed | type mismatch"
      }
    ],
    "validation_gaps": [
      {
        "script": "validate-*.sh script name",
        "doc_claims": "what the pipeline doc says is enforced",
        "doc_source": "pipeline doc making the claim",
        "issue": "script does not check this | script checks stale field name"
      }
    ]
  },
  "working_well": ["things that match the ideal — acknowledge what's good"]
}