intent-identification

# Intent Identification ## Overview Use this skill when execution is premature because the user's intent is still fuzzy. This skill is intentionally generic. It does **not** belong to YouTube, product research, coding, writing, or any single domain. Its only job is to turn a vague request into a reusable structured intent contract that other skills can consume. This skill is appropriate when: - the request can be interpreted in multiple ways - the effort difference between interpretations is meaningful - a downstream executor needs explicit constraints before acting - you need to separate **intent clarification** from **domain-specific execution** ## Prerequisites Before using this skill, confirm that intent clarification is actually needed: - the user request is still meaningfully ambiguous, underspecified, or risky to route directly - there is no more specific executor that can already act safely with the current information - you are prepared to ask only the minimum blocker questions needed for safe handoff If the request is already specific enough to execute safely, skip this skill and move straight to the downstream executor. ## Hard gate ## Hard gate - Do **not** execute domain-specific actions while using this skill. - Do **not** produce hidden execution parameters. - Do **not** guess missing intent details just to keep moving. - If the contract is not ready, return `status: NEEDS_CLARIFICATION` and keep asking. ## Core workflow 1. Understand the current request and context. 2. Ask **one clarifying question at a time**. 3. Focus on the minimum fields needed to safely route or execute later. 4. When useful, propose **2-3 interpretations or approaches** with tradeoffs and recommendation. 5. Once intent is clear enough, summarize it and ask for confirmation. 6. Output a reusable `intent_contract_v1`. ## Questioning rules - Ask one question per message. - Prefer multiple-choice when possible. - Focus on: - objective - target subject - target audience or consumer - desired deliverable - success criteria - constraints - must-include and must-exclude terms - If the user has already been specific enough, do not drag them through unnecessary questions. ## Outputs The output of this skill is always a reusable contract, not a side effect. Return exactly one structured result in one of two states: - `status: READY` when downstream execution can proceed safely - `status: NEEDS_CLARIFICATION` when blocker questions still remain The contract should be explicit enough for downstream skills to reuse without hidden assumptions or extra inferred parameters. ## Output contract ## Output contract Return one of these two shapes. ### Ready for downstream execution ```json { "contractVersion": "intent_contract_v1", "status": "READY", "intent": { "objective": "Find YouTube URLs that represent the target audience's routines and product-adjacent language", "targetSubject": "pilates", "targetAudience": "young women interested in lifestyle-led pilates identity", "deliverable": "a filtered list of long-form YouTube video URLs", "successCriteria": "returned videos should be high-signal, long-form, and useful for downstream transcript mining", "explorationAngles": [ "day in the life", "vlog", "routine" ], "constraints": { "language": "en", "minDurationSeconds": 1200, "precisionMode": "precision-first", "resultLimit": 12 }, "mustInclude": [ "pilates" ], "mustExclude": [ "shorts", "clips" ] }, "openQuestions": [] } ``` ### Not ready yet ```json { "contractVersion": "intent_contract_v1", "status": "NEEDS_CLARIFICATION", "intent": { "objective": "Find relevant YouTube content", "targetSubject": "pilates", "targetAudience": "", "deliverable": "YouTube URLs", "successCriteria": "", "explorationAngles": [], "constraints": {}, "mustInclude": [], "mustExclude": [] }, "openQuestions": [ "Which audience should these videos represent?", "Do you want daily-life vlogs, routines, podcasts, tutorials, or something else?", "What counts as a long-enough video for this task?" ] } ``` ## Field definitions - `objective`: what the user is trying to accomplish - `targetSubject`: the entity, domain, topic, or object of interest - `targetAudience`: the intended people, persona, or consumer group - `deliverable`: what downstream execution should produce - `successCriteria`: how to judge whether the result is good enough - `explorationAngles`: optional angles, modalities, or patterns to explore - `constraints`: a generic bag of explicit limitations or preferences - `mustInclude`: terms or conditions that must appear downstream - `mustExclude`: terms or conditions that must not appear downstream - `openQuestions`: unresolved blockers preventing safe downstream execution ## Genericity rule This skill must stay domain-agnostic. - It may prepare intent for a YouTube search skill. - It may prepare intent for a writing skill. - It may prepare intent for a research or sourcing skill. - It must **not** leak domain-specific output formats into the contract unless the user explicitly needs them. For example, this skill can output `explorationAngles`, but it should not output `finalQueries` for a YouTube search executor. ## Behavior summary - Clarify first. - Normalize second. - Execute nothing. - Hand off a contract, not a guess. ## Script - `scripts/validate_intent_contract.js`: validates and normalizes `intent_contract_v1` JSON for reuse by downstream scripts.