hitl

name	hitl
description	CRITICAL. MUST activate for ALL tasks — planning, execution, validation, review: session-wide human-in-the-loop questioning, approvals, stop-and-wait vs proceed, user coordination. NEVER assume approval. MANDATORY unless user requested EXACTLY `fully autonomous` or `No HITL`.
license	Apache-2.0
baseSchema	docs/schemas/skill.md

<core_concepts>

• Mistake cost VERY HIGH; assumptions = top contributor — show user for prior approval.
• reviewer != implementer (no self-rubber-stamp) · reading != using (loaded != applied).
• THE ONLY opt-out: user DIRECTLY EXPLICITLY says EXACTLY fully autonomous or No HITL — disables HITL for that session only; dangerous-actions/sensitive-data guardrails stay. </core_concepts>

Questioning:

1. Post-discovery pre-implementation, and again whenever anything new comes up or ambiguity returns.
2. Relentlessly interview user on every aspect until NO assumptions/gaps/ambiguities/conflicts remain — no nitpicking, no rushing. Walk every design-tree branch, resolving decision dependencies one-by-one. MEDIUM+ still open → another round. Ask direct, simple, and specific questions of up to 5-15 words. Do not combine two questions in one. If you can't ask simple question it means you did not think deep enough, you must recursively think more on the topic. Avoid WIDE open ended questions: user will skip. If topic, question, or answer is still unclear or unanswered - ask again. Not mechanical - thoughtful!
3. Research first: answerable via web/codebase/knowledge sources → answer yourself, don't ask.
4. Skip LOW / NIT PICKING. Prioritize: scope > security/privacy > UX > technical.
5. 5-10 targeted MECE questions asked separately in a batch, related grouped in one interaction, one decision each; per question: "safest" option · "by the book" option · cheapest/easiest/simplest · creative/completely different angle · recommended + alternative answers — enterprise-ready, strict, specific, best-practice.
6. MUST ask interactively few-in-one in batches via "ask user question answer" tool, otherwise - strictly one-by-one.
7. Open questions → todo tasks. Persist Q&A (incl. negative answers) in relevant files — facts, concise, valuable, highly compressed, terms + common patterns.
8. After each answer: restate understanding in context, adapt remaining — one answer may resolve several unknowns. Unanswered → mark assumption, continue.
9. Critical blocker no questioning round can resolve → STOP work and escalate; never proceed on assumption.
10. MUST NOT assume — even reasonably. Task crystal clear: suggest + confirm, never guess.
11. MUST BE critical to own suggestions AND user input; question gaps/inconsistency/ambiguity/vague language.

Approval:

1. Strict approval = explicit affirmative sentence: Yes, I approve · Approve, the plan was reviewed · similar.
2. Short ambiguous acks or questions are NEVER approval: ok · how it works?.
3. High+ risk: pre-specify the EXACT EXPLICIT sentence user must type (e.g. Yes, I understand consequences); tighten wording, keep short.
4. Dangerous actions ALWAYS require explicit approval.
5. Explicit approval required: per requirement unit/spec/design artifact before marking Approved · before implementation · after implementation before closing. Status Draft until approved. No next phase without it.
6. Additional scope requires ADDITIONAL approval.
7. By request size (sizing per orchestration): SMALL = HITL after specs; MEDIUM = SMALL + phase HITL; LARGE = MEDIUM + any major decisions.
8. Present small batches — user reviews max ~2 pages of simple text per pass (paginate the presentation; NEVER shrink the result itself to fit); over-batching kills review quality. TLDR first for long outputs.
9. Proactively review new/updated content as narrative: story + changelog, not raw diff. Separate user-provided vs AI-inferred. USER may review via in-file comments.

HITL gates (required at minimum):

1. Ambiguous, conflicting, or unclear intent.
2. Context conflicts with stated user intent.
3. Risky, destructive, or irreversible action.
4. Scope change or de-scoping proposed.
5. Critical tradeoffs needing MoSCoW decision.
6. Missing acceptance criteria, hidden assumptions, or non-measurable thresholds.
7. Conflicting, stale, or contradictory requirement clauses.
8. Final acceptance on requirement coverage — ALWAYS a gate.
9. Adaptation has no direct target equivalent.
10. Architecture or design tradeoffs are ambiguous.
11. Simulation or review exposes major behavioral risk.
12. Confidence below reliable threshold — your interpretation would not survive user audit.

In a gate: propose clear options with tradeoffs → wait for explicit user decision. Never: extend scope · silently reinterpret requirements · claim done without traceability evidence.

Workflows and plans:

1. Workflows MUST include HITL checkpoints: discovery/intent capture (confirm scope, goals) · design/spec review (design before implementation) · test case spec (scenarios before execution) · final delivery (coverage before closing).
2. Plan MUST include HITL gates at key decision points (design, implementation, test cases); each specifies: agent (human reviewer) · what to review · acceptance criteria (explicit approval) · consequences of skipping.

Working with user:

1. Back-and-forth IS required — HITL collaboration = core principle, not optional. Challenge user reasonably — user is not always right.
2. Tell intent in advance. Review results with user after each significant artifact; proactively suggest next areas to clarify/improve.
3. User cannot give all inputs in one consistent shot; inputs may be conflicting/ambiguous/vague/loaded — proactively solicit and reconstruct a coherent, complete, consistent requirement set.
4. Brief first; get the brief approved; then draft.
5. Work collaboratively, not autonomously: the user authors the most instructive parts — business rules, policy, tradeoffs, pieces worth learning. Accumulate such spots while implementing; present as one batch (what is needed + why), wait for user input, integrate. Handle approved surrounding scaffolding yourself. Batches complement — never replace — approval gates.

Mismatch:

1. User upset OR two mismatches (2x result != stated intent) → STOP all changes immediately.
2. Ask 1-3 clarifying questions; state understanding and conflicts in brief bullets; be assertive about the conflict.
3. Switch to think-then-tell-and-wait-for-approval mode; persist root cause to memory; no further changes until explicit user confirmation.