dev-standards-grill-task

name	dev-standards-grill-task
description	Interrogate any new task before it is persisted — extract intent, flow, domain terms, design patterns, scope, and verification with tier-gated depth. 任務創建時審問之，層層深掘以求精確。 Use when: plugin creates task, schedule work, grill request, interrogate task before planning, task intake, dartai task creation

Grill-Task

任務創建時運行。量料兩度，執行一刀。

Invocation

Called by:
  dartai: /dartai:task, skills/simple-planning, skills/adversarial-planning-loop
  workflow: /workflow:add-task
Delegates to:
  risk-pipeline:classify (optional; Step 5 — skipped if plugin absent or disabled)
Returns:
  task_spec (required)  — includes task_spec.risk from risk-pipeline:classify
                          or {enabled: false} when pipeline disabled/missing
  backflow_writes (list of {skill, path, changes}; may be empty)

Step 0 — Read project context (silent)

詢問前先讀。上下文愈豐，問題愈少。

Prefer LCI (lci:search for symbols/terms, lci:explore for module maps) over Grep when exploring; fall back to Grep/Read if the lci plugin is unavailable. If a question can be answered by exploring the codebase, explore instead of asking.

• .claude/rules/* — project posture (security, testing, TDD level, architecture style)
• CLAUDE.md or .claude/CLAUDE.md — project identity
• docs/DOMAIN.md or docs/domain/*.md — canonical domain terms
• docs/user-stories/ — existing stories
• docs/user-flows/ — existing flows
• docs/design-guidelines.md and any component library READMEs detected
• Recent related tasks (for dartai: same folder; for workflow: .workflow/loop-state.json.tasks[])
• LCI search results for the nouns and verbs in the raw request

Step 1 — Classify tier

判斷此請求屬何級：

Tier	Indicators	Action
Minimal	1 file, trivial, unambiguous (typo, text, one-line fix)	Skip grill entirely, return one-line spec, done
Standard	2-5 files, single feature/fix, minor clarification needed	Run full layered interrogation
Comprehensive	5+ files, multiple criteria, significant discussion	Run full layered interrogation, all layers
Architectural	cross-cutting, multiple subsystems, new patterns	Run full layered interrogation, plus escalation if too large

File counts above are rough indicators of interrogation depth, not gates — judge by context cost (file size + diff), not raw count.

Minimal 級立即返回：

task_spec:
  requested: "<user's exact words>"
  tier: minimal
  scope:
    files_to_modify: [<single file>]
  acceptance: [<one-line criterion>]
backflow_writes: []

Step 2 — Layered questions (standard tier and above)

先讀後問，事實自查、決策方問。 凡探碼可答之事實（現有詞、模式、調用者），自查勿問；唯決策屬用戶——呈之待答。若「讀自」已答，摘要已知，問「此仍確乎？」勿重頭。

批量前置提問，勿逐一原子問。 提問前，先列各層之待問清單，將連動或同 sub-domain 之問題束為一組，一次呈多問（AskUserQuestion 每次至多 4 問；同輪跨層併問無妨）。此遵 [[ideation]] 之 strategy-bundle 慣例與項目 batch/front-load 偏好——串行單問耗 wall-clock。僅當一問之答會重構其餘諸問時，方單獨先問該問。

Layer 1 — Intent

• Reads from: docs/user-stories/
• If missing, asks: Who benefits? What specific outcome? How is success measured?
• Writes back via: project-local write-user-story (if present)

Layer 2 — Flow

• Reads from: docs/user-flows/
• If missing, asks: Entry point? What adjacent steps? What exit criteria?
• Writes back via: project-local define-user-flow (if present)

Layer 3 — Domain

• Reads from: docs/DOMAIN.md
• If missing, asks: What is the canonical term for this concept? Are there synonyms to avoid?
• Writes back via: project-local domain-update (if present), or domain-init if no DOMAIN.md exists yet

Layer 4 — Design

• Reads from: docs/design-guidelines.md, component library README, existing patterns via LCI
• If missing, asks: What pattern should this follow? Is there an existing component to reuse?
• Writes back via:

Invoke the Skill tool with skill: dev-standards:update-rules — 將設計規範寫入項目規則。

Layer 5 — Scope

• Reads from: LCI search on nouns/verbs
• If missing, asks: Which files need to change? What is explicitly NOT included?
• Writes back: task spec only (no permanent writeback)

Layer 6 — Verification

• Reads from: .claude/rules/testing.md, .claude/rules/tdd.md
• If missing, asks: How is done measured? Is there a RED test planned? Any manual verification step?
• Writes back: task spec only (no permanent writeback)

Domain discipline (build the glossary as you grill)

審問之際，同步維護 .claude/rules/glossary.md：

• 以詞彙表為矩相詰。 用戶術語與現有定義相牴 → 立即指出，問何義為準。
• 磨礪模糊語。 含混或 overloaded 詞 → 提出精確 canonical 名（「'account' — Customer 抑 User？」）。
• 具體情景。 以特定 edge-case 情景壓測領域關係。
• 代碼交叉核對。 lci:search <term> —— 代碼若與用戶所言相悖，浮之。
• 逐詞即寫 glossary.md（勿批處理），術語一解即更新。格式與機制見 [[glossary]] 及 skills/glossary/CONTEXT-FORMAT.md。
• 慎提 ADR。 唯難逆轉 + 無上下文則意外 + 真實權衡三者俱備時方提；經 [[decide]] 路由（其理一行索引與 docs/adr/ 提升）。

Step 3 — Graceful degradation for absent writers

調用任何項目本地寫手技能前，先探其是否存在：

test -f .claude/skills/<skill-name>/SKILL.md

若無，不中止。在任務規格中記 TODO：

notes:
  - "TODO: install .claude/skills/write-user-story to persist Intent layer gap"

下次 grill-task 若項目已安裝（藉

Invoke the Skill tool with skill: dev-standards:add-skill — 為項目添加缺失的寫手技能。

或後續 setup-project 運行），自動銜接。

插件本地寫手（decide、update-rules、update-project、add-skill）常備，無需探測。

Step 4 — Hard caps

• 初輪後最多 2 輪追問
• 縱Architectural級，最多 12 問
• 若達上限仍模糊，上報：返回 task_spec.verdict = "TOO_LARGE_TO_GRILL"，建議拆分任務
• 若 Step 5 風險分級出 risk.vector.scalar > 25（顯超 architectural 預算），亦觸 TOO_LARGE_TO_GRILL，附 reason: risk_budget_exceeded；若 risk.verdict == split_required，將 risk.split_proposal 併入回報供呼叫方直接建片，併附 recommended_action: "Split per proposal then re-run grill"

Step 5 — Risk classification (risk-pipeline integration; authoritative when enabled)

風險分級若插件在。啟用時風險裁決為權威——驅 TOO_LARGE_TO_GRILL 觸發（risk.vector.scalar > 25 或 verdict == split_required）及下游 pipeline_tier 路由。不在或 enabled: false 則舊流繼，task_spec.risk = {enabled: false} 顯記之，層級邏輯回退驅動管道（legacy fallback path）。

可用性檢 (Availability check)

先探二事：

• 技藝存否：plugins/risk-pipeline/skills/risk-classify.md 可達
• 配置啟否：.claude/rules/risk.md frontmatter risk_pipeline.enabled == true

二者缺一 → 跳此步，task_spec.risk = {enabled: false}，續舊流。無錯，禁用為合法態。

調用 (Invocation)

Invoke the Skill tool with skill: risk-pipeline:classify — 任務級風險分級，出向量、裁決、管道層。

入參：

• task_id — dartai 上下文或合成識別符
• task_spec — 當前已審之規格主體
• touched_files — 自 Step 1 層級偵測導出

出二態之一：

• {enabled: false} → 插件或配置禁用，記「risk-pipeline disabled」，task_spec.risk = {enabled: false}，跳合併
• 完整分級輸出 → 併入 task_spec.risk

合入 (Merge into task_spec)

規格附：

task_spec:
  # ... 原欄不動 ...
  risk:
    enabled: true
    vector: {b, d, s, r, u, scalar, crit_axes}
    verdict: ok | split_required | refactor_first_required | escalate
    pipeline_tier: smoke | light | dim_matched | architectural
    required_reviewers: [...]
    model: haiku-4.5 | sonnet-4.6 | opus-4.7
    tdd_required: <bool>
    split_proposal: [...]      # 僅 verdict == split_required 時出
    findability_notes: "..."   # 切片決策或 findability 檢查述

向後兼容 (Legacy fallback when disabled)

• task_spec.risk = {enabled: false} 顯記，非略 —— 呼叫方可查而無需揣
• 層級邏輯驅管道（fallback path），無風險驅動裁決
• 不報錯，禁用為合法態
• 其餘 task_spec 欄一如既往，risk 純加性
• 啟用時風險驅 verdict/scalar/pipeline_tier；禁用時層級驅，二態皆合法

Step 6 — Planning-Time Quality Review

呈確認屏前，單輪自審 task_spec。不派對抗代理。

Quality Review Checklist

planning_quality_review:
  directness:
    check: "Does the spec attack the problem directly, or does it wander through indirection?"
    pass_if:
      - "The smallest change that delivers the request is identified"
      - "No preparatory 'setup' steps that don't directly advance the goal"
      - "Solution path is a straight line from problem to deliverable"
    fail_if:
      - "Introduces intermediary abstractions not required by the problem"
      - "Adds configuration or indirection without multiple immediate consumers"

  problem_solution_fit:
    check: "Is the proposed solution appropriate for this specific codebase?"
    pass_if:
      - "Uses patterns and libraries already present in the codebase"
      - "Leverages existing utilities rather than introducing new ones"
      - "Fits naturally into the existing architecture"
    fail_if:
      - "Imports a new pattern when an established one suffices"
      - "Creates a new subsystem for a localized change"
      - "Ignores existing conventions (error handling, logging, testing style)"

  testability:
    check: "Is every acceptance criterion extremely testable?"
    pass_if:
      - "Each criterion can be verified by a single RED→GREEN test cycle"
      - "Criteria are observable (output, behavior, state), not subjective"
      - "Edge cases are enumerated as separate criteria"
      - "Test approach matches the project's existing test runner and patterns"
    fail_if:
      - "Criteria use words like 'better', 'improved', 'user-friendly'"
      - "No clear pass/fail condition for a criterion"
      - "Testing would require manual verification or external coordination"

  overengineering_guard:
    check: "Is there any overengineering in the planned solution?"
    pass_if:
      - "No abstractions with only one consumer"
      - "No generic interfaces for a single implementation"
      - "No 'extensible' or 'configurable' additions not driven by current needs"
      - "No horizontal-layer planning; only vertical slices"
    fail_if:
      - "Plans to build frameworks instead of solutions"
      - "Adds parameterization for hypothetical future cases"
      - "Introduces classes/modules that don't simplify the immediate change"

  solution_depth:
    check: "Has the solution been thoroughly explored without overcomplicating?"
    pass_if:
      - "Trade-offs between at least two reasonable approaches were considered"
      - "The chosen approach is documented with a one-sentence rationale"
      - "Known edge cases and error paths are addressed in the plan"
      - "Integration points with existing code are identified"
    fail_if:
      - "Only one approach was considered"
      - "No mention of how errors or edge cases are handled"
      - "Integration points are vague or missing"

五項皆通方呈確認屏；不通則調整規格，重審。

Step 7 — Confirmation screen

寫入任何通道前，呈任務規格與所有待回流寫入，合為一屏：

Grilled Task Spec
=================
<task spec YAML>

Pending backflow writes
=======================
- write-user-story: docs/user-stories/US-43.md  (new, 42 lines)
- domain-update:   docs/DOMAIN.md  (append LineItem definition)

Approve [y] / Edit field [e] / Another round [r] / Abort [x] ?

y：原子性執行所有回流寫入（暫存後一次提交），返回任務規格給調用者。 e：詢問修改哪個字段。 r：回 Step 2，追加問題（仍受上限約束）。 x：不寫任何內容，返回 task_spec.verdict = "ABORTED"。

Output format

task_spec:
  requested: "<user's exact words>"
  tier: standard | comprehensive | architectural
  refs:
    user_story: docs/user-stories/US-42.md    # or null
    flow: docs/user-flows/checkout.md         # or null
    domain: [Order, LineItem]
    design: rules/design-guidelines.md#buttons
  scope:
    files_to_modify: [<paths, max 5>]
    not_included: [<explicit exclusions>]
  acceptance:
    - <RED→GREEN criterion 1>
    - <RED→GREEN criterion 2>
  verification:
    runner: vitest                             # or pytest, go test, etc.
    manual: <optional manual check>
  risk:                                        # from risk-pipeline:classify (Step 5)
    enabled: true | false                      # false when pipeline missing/disabled — all other risk.* fields absent
    # when enabled: vector, verdict, pipeline_tier, required_reviewers, model, tdd_required, split_proposal?, findability_notes
  notes: []                                    # populated on graceful degradation
  verdict: OK | TOO_LARGE_TO_GRILL | ABORTED
  # TOO_LARGE_TO_GRILL may carry reason: risk_budget_exceeded + recommended_action + risk.split_proposal

backflow_writes:
  - skill: <skill-name>
    location: plugin-local | project-local
    path: <file path written>
    summary: <one line>

Discipline

• 批量前置提問。 束連動問為一組，一次呈多問（AskUserQuestion 至多 4）；勿逐一原子串問。唯「答之會重構其餘」之樞紐問方單先問。
• 有合理選項時用多選；無則開放作答。
• 事實自查、決策方問。 探碼可答者自查勿問；決策屬用戶。
• 共識閘（confirmation gate）。 未經 Step 7 確認屏，決不視為達成共識、決不逕自付諸實現或觸發下游規劃。
• Minimal 級絕不審問。審問錯字修改，誤甚於帶錯上線。
• 決不將項目本地寫手技能內容嵌入此技能。調用之。
• 決不寫入部分回流——收集、確認、原子性提交。
• 遵守 .claude/rules/karpathy-principles.md：不確定時反推，呈現取捨，不「假設跑」。

grilling discipline（confirmation gate + facts-vs-decisions）adapted from mattpocock/skills v1.1 (MIT), skills/productivity/grilling. Upstream's "one question at a time" rule is intentionally not carried — this repo front-loads and batches decisions instead.

Related skills

Invoke the Skill tool with skill: dev-standards:refactor-first-assessment — 規劃技能在 grill-task 後調用，決定是否需預備重構步驟。

Invoke the Skill tool with skill: dev-standards:decide — 未決架構問題之回流寫手。

Invoke the Skill tool with skill: dev-standards:update-rules — 新項目規則之回流寫手。

Invoke the Skill tool with skill: dev-standards:add-skill — 新項目專屬技能之回流寫手。

Invoke the Skill tool with skill: dev-standards:update-project — 項目描述變更之回流寫手。