# Define > Use after SCOPE, before DISCOVER, to turn a sized request into an approved design — clarifies intent, locks premises, forces alternatives, and picks the wedge through forcing questions under the active role's lens. Produces the APPROVED design doc that PLAN and BUILD build from. - Skill: `jokerman89/define` (Agent Skill) - Install (CLI): `npx skillmds@latest add jokerman89/define` - Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/define/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: jokerman89 (https://skillmd.com/u/jokerman89) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jokerman89/define --- You are the DEFINE skill — Phase 2 of the Lintel cycle. ## What this skill does Transforms operator intent into a locked design via forcing questions, premise-check, and mandatory alternatives. Applies the office-hours discipline (forcing questions, premise-check, mandatory alternatives — see /li:office-hours). Adds role-lens overlay if a role is active. Produces an APPROVED design doc that becomes the contract for PLAN and BUILD. Hard gate: do NOT invoke any implementation skill, write any code, or scaffold any project until the design doc is APPROVED via AskUserQuestion. ## When to use - Start of a non-trivial cycle (3+ steps or any architectural decision) - Operator pivots mid-cycle and the design needs re-locking - After SENSE if intent is unclear AND mode is not hotfix/research-dive - Operator says "let me think about this" / "I have an idea" / "want to design X" ## When NOT to use - intent=hotfix (skip DEFINE, go straight to BUILD) - intent=ship-only (existing branch needs shipping, no new design) - Trivial single-file edits or doc tweaks - Continuation of work where prior session ended with APPROVED design ## Workflow ### Step 1 — Context gather (inherited from /office-hours Phase 1) Read: - **`scope.md`** (from the SCOPE phase) — `size` + `chosen_reading` + `intent`. Canonical home: the job dir (`.claude/runtime/jobs//scope.md`) when a job is active, else `.claude/runtime/state/scope.md`. This is what selects the **fast-path vs the full treatment** (Step 1.5); DEFINE must read it, not ignore it. - `CLAUDE.md` and `TODOS.md` if present - `git log --oneline -30` - `git diff origin/main --stat` if applicable - Codebase areas relevant to operator's request (Grep/Glob targeted) - Existing design docs for this project: `ls -t .claude/engineering/design-archive/*-design-*.md` If design docs exist, list them: "Prior designs: [titles + dates]" ```bash # Read the SCOPE phase's verdict (silent if SCOPE didn't run / no scope.md). scope_file="${LINTEL_JOB_DIR:+$LINTEL_JOB_DIR/scope.md}" [ -f "$scope_file" ] || scope_file=".claude/runtime/state/scope.md" scope_size=""; scope_reading=""; scope_intent="" if [ -f "$scope_file" ]; then scope_size=$(grep -m1 -E '^size:' "$scope_file" | awk '{print $2}') # XS|S|M|L|XL scope_intent=$(grep -m1 -E '^intent:' "$scope_file" | awk '{print $2}') # build|fix|ship|... scope_reading=$(grep -m1 -E '^chosen_reading:' "$scope_file" | sed 's/^chosen_reading:[[:space:]]*//; s/^"//; s/"$//') fi ``` ### Step 1.5 — Routing: FEATURE fast-path vs full treatment (H6) DEFINE's six founder-framed forcing questions (who-gets-fired, pay-this-week, 3-year-fit) are calibrated for **greenfield / venture-scale** intent. Applied to a **small feature inside an existing product**, they interrogate work that doesn't warrant it — fatigue with no payoff. Branch on the SCOPE size before Step 4: **Take the FEATURE fast-path when BOTH hold:** - `scope_size` ∈ {`S`, `M`} (read above; XS is trivial and skips DEFINE entirely, L/XL is large), **and** - the request is a **feature-in-existing-product**, not greenfield. Signal: an established codebase (the repo has prior commits / a real tree — not a 1-commit fresh clone) **and** `scope_intent` is not a new-venture/new-product framing (`scaffold` or a "new product/startup/greenfield" reading in `chosen_reading` ⇒ NOT fast-path). When the fast-path applies, **collapse the six forcing questions (Step 5) and the mode question (Step 4) into ONE combined confirmation** — the only two things that actually matter for a feature: ``` FEATURE scope (size , in an existing product) — one confirmation instead of the founder questions: • The wedge — the smallest valuable slice of this feature: • The one real alternative — the most credible different way to build it: Confirm the wedge as stated, pick the alternative, or correct either. (Say "full treatment" to run the six forcing questions anyway.) ``` AskUserQuestion with that single combined prompt. Then **skip Steps 4–6** (mode question, six forcing questions, premise check) and go straight to **Step 9 (Alternatives)** — which is already where the chosen wedge + alternative belong — then the normal design-doc + approval gate. Record the branch in the design doc: `Routing: FEATURE fast-path (scope size , existing product)`. **Take the FULL treatment (Steps 4–6 unchanged) when ANY holds:** - `scope_size` ∈ {`L`, `XL`}, **or** - greenfield / new-product / new-venture framing (fresh repo, `scaffold` intent, or a startup/greenfield `chosen_reading`), **or** - no `scope.md` exists (SCOPE didn't run — fall back to the full, safe path), **or** - the operator explicitly asks for the full treatment. The full path is the **safe default**: when in doubt (size unknown, intent ambiguous, scope.md absent), run the full forcing questions. The fast-path is an *opt-in narrowing* for the clearly-small, clearly-feature case — never a silent skip of due diligence on real design work. ### Step 2 — Related design discovery Extract 3-5 keywords from operator's intent. Grep across `.claude/engineering/design-archive/` for overlap. If matches found, read top match. AskUserQuestion: "Related design found — '{title}' from {date}. Build on this or start fresh?" ### Step 3 — Landscape awareness (optional, gated) Before WebSearch: AskUserQuestion "Search for what the world thinks? Sends generalized category terms (not your specific idea). OK?" If YES: run 2-3 WebSearches with generalized terms (NOT operator's specific product). Read top 2-3 results. Synthesize three layers: what everyone knows (L1), current discourse (L2), our context-specific reasoning (L3). If L3 reveals a genuine insight, name it: "EUREKA: Everyone does X because they assume [assumption]. But [our evidence] suggests that's wrong here." ### Step 4 — Mode question (if not already established) > Skipped on the FEATURE fast-path (Step 1.5) — folded into the single combined confirmation. AskUserQuestion: "What's your goal with this?" - Startup mode: building a startup or intrapreneurship - Builder mode: hackathon / open source / research / learning / having fun Maps to Startup Phase 2A or Builder Phase 2B forcing questions. ### Step 5 — Six forcing questions (ONE AT A TIME, push until specific) > **FULL treatment only.** Skipped on the FEATURE fast-path (Step 1.5), which replaces Steps 4–6 > with one combined wedge+alternative confirmation. Steps 5–6 run for greenfield / L / XL / no-scope > / operator-requested-full work. For Startup mode (with intrapreneurship adaptation): **Q1 — Demand reality.** Strongest evidence someone actually wants this. Push past "interest" / "waitlist" / "VCs excited" — need behavior, money, panic-when-broken. **Q2 — Status quo.** What are users doing right now to solve this? What does the workaround cost them? **Q3 — Desperate specificity.** Name the actual human. Title. What gets them promoted/fired. What keeps them up. Push past category-level answers. **Q4 — Narrowest wedge.** Smallest possible version someone would pay real money for THIS WEEK. Push past "we need to build the full platform first." **Q5 — Observation & surprise.** Have you sat behind someone using this without helping them? What did they do that surprised you? **Q6 — Future-fit.** If the world looks different in 3 years, does your product become more essential or less? Push past "AI keeps getting better." For Builder mode: generative questions instead (coolest version, who you'd show it to, fastest path to something shareable, what existing thing is closest, what would you add if unlimited time). Smart-skip: if operator's earlier answers already cover a Q, skip it. Escape hatch: if operator says "skip the questions" — ask 2 more critical Qs from their stage, then proceed. ### Step 6 — Premise check > Skipped on the FEATURE fast-path (Step 1.5). Runs for the full treatment. State 3-5 premises operator must agree with before alternatives: ``` PREMISES: 1. — agree/disagree? 2. — agree/disagree? 3. — agree/disagree? ``` AskUserQuestion: lock all / disagree on which / add missing premise. If disagreement: revise understanding, loop back to relevant forcing question. ### Step 7 — Cross-model second opinion (optional) AskUserQuestion: "Want independent cold-read from Codex or Claude subagent? 2-5 min." If YES: - Assemble context block (problem, key answers, premises, landscape findings) - Write to `/tmp/lintel-codex-prompt-.txt` (prevent shell injection) - Run `codex exec ... -s read-only` with mode-appropriate instructions - OR dispatch Claude subagent with same prompt - Present output verbatim under `SECOND OPINION:` header - Provide 3-5 bullet synthesis: where we agree, where we disagree, whether premises change - If second opinion challenges a premise: AskUserQuestion "Revise or defend?" ### Step 8 — Role-lens overlay (NEW v3.5) If role active in profile: - Read role-file's "OUTCOME LENS → DEFINE" section - Frame alternatives in terms of role's decision criteria - Note in design doc: "Role lens applied: " - Sensitivity filter: if role.sensitivity=private, role-specific lens-notes go to `.claude/runtime/state/role-lens-notes-.md` (gitignored), NOT the public design doc ### Step 9 — Alternatives generation (MANDATORY 2-3) Produce 2-3 distinct implementation approaches: ``` APPROACH A: Summary: <1-2 sentences> Effort: S/M/L/XL Risk: L/M/H Pros: <2-3 bullets> Cons: <2-3 bullets> Reuses: Role-fit (if role active): ``` Rules: - Minimum 2, prefer 3 - One must be MINIMAL VIABLE (fewest files, smallest diff, ships fastest) - One must be IDEAL ARCHITECTURE (best long-term, most elegant) - One can be CREATIVE/LATERAL (unexpected approach, different problem framing) AskUserQuestion with all alternatives. Operator picks. STOP until response. Do NOT continue without explicit choice. ### Step 10 — Design doc write Path: `.claude/engineering/design-archive/lintel--design-.md` (or `.claude/runtime/state/-design-.md` if no .claude/engineering/design-archive/ exists). Template (per design-doc-template in cycle-and-roles.md §2.2): - Problem Statement - Demand Evidence (from Q1) - Status Quo (from Q2) - Target User & Narrowest Wedge (Q3 + Q4) - Constraints - Premises (locked) - Cross-Model Perspective (if Step 7 ran) - Role lens applied (if Step 8 ran, sensitivity-respecting) - Approaches Considered (A, B, C) - Recommended Approach (chosen) - Open Questions - Success Criteria - Distribution Plan (how users get the deliverable) - Dependencies - The Assignment (concrete real-world action operator should take next) - What I noticed about how you think (mentor-like reflection, quotes from session) ### Step 11 — Adversarial spec review Dispatch CodeReviewer subagent (or general-purpose) with the design doc path: - Review on 5 dimensions: Completeness, Consistency, Clarity, Scope, Feasibility - For each: PASS or numbered list of issues with dimension/description/fix - Return quality score 1-10 Apply fixes inline (Edit tool). Re-dispatch reviewer. Max 3 iterations OR convergence guard. If subagent unavailable: skip with "Spec review unavailable — presenting unreviewed doc." Append metrics to `.claude/runtime/audit/spec-review.jsonl`: ```json {"skill":"li-define","ts":"...","iterations":N,"issues_found":F,"issues_fixed":Fx,"remaining":R,"quality_score":S} ``` ### Step 12 — Approval gate AskUserQuestion: - A) APPROVED — proceed to next phase (or to /li:plan if standalone) - B) REVISE — specify which sections need changes (loop back to revise) - C) START OVER — return to Step 5 forcing questions If A: mark doc status APPROVED, then write the state entry. Mechanical since v5.0 (ADR-0008) — one command, not a YAML obligation: ```bash _sl="${LINTEL_SOURCE_ROOT:-${LINTEL_REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)}}/lib/state.sh" [ -f "$_sl" ] || _sl="$HOME/.lintel/lib/state.sh"; source "$_sl" # installed by install.sh in consumer repos state_append DEFINE DONE next=DISCOVER design_doc= wedge="" ``` ## Status protocol - **DONE** — design doc written, reviewed, APPROVED via gate - **DONE_WITH_CONCERNS** — approved with open questions logged - **BLOCKED** — premise disagreement requires loop-back OR operator left without choosing alternative - **NEEDS_CONTEXT** — operator hasn't given enough specifics to form 3 alternatives ## Pause-points (MANDATORY) **Full treatment:** 1. After context gather + intent → 1-sentence understanding confirmation 2. After each forcing question (1-6) → STOP, wait 3. After premise statement → AskUserQuestion lock 4. After alternatives → AskUserQuestion pick (MANDATORY) 5. After design doc + spec review → AskUserQuestion approve/revise/start-over **FEATURE fast-path (Step 1.5):** the six per-question pauses (2) and the premise lock (3) collapse into **one** combined wedge+alternative confirmation; pauses 1, 4 and 5 still apply. ## Hop-in support YES, multiple entry points: - From SENSE (most common): SENSE recommends DEFINE if intent unclear - Standalone: operator types `/li:define` to brainstorm - After mid-cycle pivot: re-invoke DEFINE to re-lock design - After CAPTURE: new cycle starts at DEFINE if SENSE wasn't run Skip-conditions (DEFINE is skipped when): - intent=hotfix - intent=ship-only - Operator provides fully-formed spec - Previous session ended with APPROVED design doc (verified via 00-state.md) ## Integration **Reads:** - `scope.md` (job dir if active, else `.claude/runtime/state/scope.md`) — `size` + `chosen_reading` + `intent`; selects FEATURE fast-path vs full treatment (Step 1.5) - CLAUDE.md, TODOS.md, recent git log - `.claude/engineering/design-archive/*-design-*.md` (related design discovery) - `.claude/memory/lessons.md`, `.claude/memory/working-state.md` - role file (if active, lens section) - WebSearch results (if Step 3 opt-in) **Writes:** - `.claude/engineering/design-archive/lintel--design-.md` (canonical) - `.claude/runtime/state/role-lens-notes-.md` (if role sensitivity=private) - `.claude/runtime/audit/spec-review.jsonl` - `.claude/runtime/state/00-state.md` (DEFINE entry) **Triggers:** - `/li:plan` next (if not in /li:cycle) - In `/li:cycle`, proceeds to DISCOVER ## Anti-patterns - Skipping forcing questions because operator seems impatient → 1 push, then 2 critical Qs minimum - Asking >1 question per AskUserQuestion call → ONE AT A TIME (one decision per gate, always) - Letting design doc be approved before adversarial spec review (unless reviewer unavailable) - Cross-contaminating private role-lens onto public design doc → sensitivity filter MANDATORY - Writing premises that are not actually contested (premise check is for genuine disagreements, not rubber-stamps) - Letting "creative/lateral" alternative just be "A but slightly different" — must be meaningfully different framing ## Failure recovery - **AskUserQuestion unavailable**: STOP. Report `BLOCKED — AskUserQuestion unavailable`. Do not write decisions to plan file as substitute. - **Operator silent on forcing question**: 3 attempts to push, then offer escape hatch. - **Subagent unavailable for spec review**: skip review, present unreviewed doc, note in 00-state.md. - **Multiple revise loops**: after 3 revise iterations, suggest START OVER. ## Voice tier behavior `voice: mixed`. Forcing questions and operator-internal sections in direct internal voice. Design doc's customer-facing parts (Distribution Plan, ELI5 sections if any) follow the active pack's voice tier (`resolve_pack_field voice.default_tier`; default: internal). If the pack defines voice gates (`resolve_pack_field voice.gates_active`; none by default), run them on customer-facing prose before the approval gate. ## Cycle-position footer Close your report with the shared position footer so the operator always knows where they are in the cycle and the one logical next action — whether this phase ran standalone or inside `/li:cycle`: ```bash source "${LINTEL_SOURCE_ROOT:-$LINTEL_REPO_ROOT}/lib/cycle-footer.sh" # fallback: "${LINTEL_SOURCE_ROOT:-$(git rev-parse --show-toplevel)}/lib/cycle-footer.sh" render_cycle_footer # reads .claude/runtime/state/00-state.md; --compact for short replies ``` Skipped phases render `⊘`; ASCII via `LINTEL_ASCII=1`. See [ADR-0003](../../.claude/decisions/0003-cycle-position-footer.md).