kenoxa/do-frame

Phases: orient → clarify → investigate → handoff. Triangulates codebase evidence (run-explore) with human intent (run-discuss). Produces frame_artifact (see references/frame-dispatch.md). Never prescribes HOW.

Artifact schema and field mapping: references/frame-dispatch.md.

Phases

| # | Phase | Type | Skills | |---|-------|------|--------| | 1 | Orient | R — invoke skill(s) | /run-explore + adaptive | | 2 | Clarify | C — invoke /run-discuss | /run-discuss (scope=frame) | | 3 | Investigate | G — adaptive for blocking unknowns | skill matched to unknown type | | 4 | Handoff | mainthread | — |

1. Orient

Two sub-steps — question generation before exploration:

1. Generate exploration questions (mainthread) — 3-5 objective codebase-factual questions from user input. Target how code works now — no desired outcomes, direction, or solution-space references.
2. Invoke /run-explore with those questions as exploration argument — not the raw user problem.

Scan input for adaptive signals:

• Defect symptoms (errors, crashes, data loss, missing records, inconsistent state, unexpected behavior, "drops", "gaps", "intermittent") → also invoke /run-debug
• Coupling/module/boundary language → also invoke /run-architecture-audit

Skip when input is purely conceptual. Carry orient key_findings + risks into clarify as codebase_signals.

2. Clarify

Invoke /run-discuss with scope: frame, goal from user input, and codebase_signals from orient. Returns discuss_artifact — projection into frame state defined in lens reference.

3. Investigate

Target blocking unknowns from clarify. Match skill to unknown type:

• Code structure unknowns → /run-explore with depth queries
• Defect unknowns → /run-debug with targeted hypothesis
• Architecture unknowns → /run-architecture-audit with focused scope
• External unknowns → /run-research for ecosystem context

Max 2 rounds. Zero-dispatch when no blocking unknowns remain — log with rationale.

4. Handoff

Verify Phase Trace has rows for orient, clarify, investigate, handoff.

Assemble frame_artifact per references/frame-dispatch.md. When a blocking unknown is feasibility-related, redirect to /do-design (WHAT/HOW escape hatch).

Spec persistence: When confidence is high or medium, offer to persist frame_artifact to docs/specs/{YYWW}-<slug>/spec.md. User confirms. {YY}{WW} = 2-digit year + ISO week; multiple specs per week allowed (e.g., 2614-implementer-standard-tier).

Carry session ID into /do-design.

Confidence-gated:

| Confidence | Declaration | |------------|-------------| | high | "Framing complete. Proceed with /do-design for solution design." | | medium | "Framing complete with open unknowns. Proceed with /do-design or resolve first." | | low | "Needs further investigation." |

STOP after declaration. User decides next step.

Anti-Patterns

• Prescribing HOW: solutions, implementation approaches, architecture decisions
• Using only run-explore when signals indicate run-debug or run-architecture-audit
• Inlining Socratic interview logic instead of invoking run-discuss
• Ranking or recommending options — framing maps the problem, not the solution space
• Skipping orient when input is codebase-adjacent
• Carrying blocking unknowns past handoff without flagging confidence
• "The user already described the problem, skip orient" — user description is hypothesis, not codebase fact
• "I can clarify inline without run-discuss" — run-discuss enforces propose-and-refine discipline; inlining drifts to open-ended questions
• "No blocking unknowns, skip investigate" — zero-dispatch is valid, but log rationale; skipping the phase is not

Completion

• Phase Trace has rows for orient, clarify, investigate, handoff [E3]
• frame_artifact written to .scratch/<session>/ with constraints + success criteria [E2]
• Confidence declared (high/medium/low) with basis [E2]