--- name: plan-work description: > (What) Decompose work into ≤9 unit-works with CONTRACTs and clarity %. (When) New work request, or sub-decomposition of low-clarity units. (Why) CONTRACTs before execution. (How) 5W1H gathering → search → decompose → write WP. argument-hint: "[work description or WP path for decomposition]" metadata: author: David Seo of GEM².AI version: 11.1.0 allowed-tools: - Read - Write - Bash(date *) - Bash(uuidgen *) --- (* TPMN SKILL — plan-work *) (* === Input === *) A ≜ [ work: 𝕊, (* what needs to be planned — may be terse or detailed *) project_slug: 𝕊, time_stamp: 𝕊, (* ISO8601 — when this planning was triggered *) parent_wp: Path?, (* ⊥ for top-level, path for sub-decomposition *) parent_unit_index: ℕ? (* which unit in parent is being decomposed *) ] (* === Output === *) B ≜ [ wp_path: Path, (* e.g., ".gem-squared/work-plan/WP-ST-57.md" *) wp_id: 𝕊, (* local identifier, e.g., "WP-ST-57" *) task_id: 𝕊, (* uuid8 — local-generated *) created_at: 𝕊, (* ISO8601 — recorded in WP file header *) unit_count: ℕ, (* 1-9 *) avg_clarity: ℕ, (* 0-100, average across all units *) references_used: Seq(𝕊)? (* patterns that informed the plan *) ] (* === Precondition === *) P ≜ work ≠ ⊥ ∧ project_slug ≠ ⊥ ∧ ".gem-squared/work-plan/" exists (* === 5W1H Dimensions === *) (* These 6 dimensions must be resolved before decomposition begins. *) (* The AI extracts what is already present in `work`, then asks human *) (* only about missing or ambiguous dimensions. *) DIMENSIONS ≜ [ WHAT: 𝕊, (* Scope — what exactly needs to change or be built *) WHY: 𝕊, (* Motivation — business reason, user need, or technical debt *) WHO: 𝕊?, (* Stakeholders/actors — who requested, who is affected, who reviews *) WHERE: 𝕊, (* Target — runtime/deployment environment (web browser, mobile, local, Docker, cloud) + which files/modules in existing codebases. NEVER tech stack — that is HOW *) WHEN: 𝕊?, (* Timeline/ordering — urgency, dependencies, sequencing constraints *) HOW: 𝕊? (* Tech stack + approach — frameworks, libraries, languages, architecture pattern, what to avoid. Tech choices belong HERE, not in WHERE *) ] (* WHAT and WHERE are always required — without them, decomposition is guessing. *) (* WHY is required for top-level WPs (parent_wp = ⊥), optional for child WPs. *) (* WHO, WHEN, HOW are optional — ask only if genuinely unclear. *) (* === Transform === *) F ≜ << 1. Gather 5W1H context (smart extraction): Parse `work` argument to extract existing 5W1H dimensions. FOR each dimension in {WHAT, WHY, WHO, WHERE, WHEN, HOW}: IF clearly stated in work → mark as RESOLVED, record extracted value. IF partially stated or ambiguous → mark as UNCLEAR. IF absent → mark as MISSING. Determine which dimensions need human input: Required: WHAT must be explicit (not just a vague noun). Required: WHERE must be identifiable (target environment or file/module scope). Required (top-level only): WHY must be stated (not "because user asked"). Optional: WHO, WHEN, HOW — ask only if genuinely needed for decomposition. IF any required dimension is MISSING or UNCLEAR: Ask human for the missing dimensions. Show what was extracted, highlight what is missing. Use concise targeted questions, not a form. Example: "WHERE: which files/modules does this affect?" (existing codebase) Example: "WHERE: what is the target environment — web, mobile, local, Docker, cloud?" (greenfield) Example: "WHY: what problem does this solve or what need does it serve?" Example: "HOW: which tech stack/framework/language?" (greenfield) NEVER ask tech stack under WHERE — tech stack is always HOW. IF parent_wp ≠ ⊥ (sub-decomposition): Inherit WHY, WHO, WHEN from parent WP — only ask about WHAT, WHERE, HOW if the parent unit's CONTRACT doesn't already specify them. Record resolved 5W1H as context for step 2 (decomposition) and step 3 (Objective section). 2. Search for relevant patterns via /search-kg: Invoke /search-kg(query=work, project_slug, scope=all, limit=5). Tag-based search on archive/ + work-plan/ files. Also: Read project skill references/ for project-specific context. Record references_used from /search-kg B.results. 3. Decompose into 1-9 unit-works (Miller's law: 7±2). Use resolved 5W1H context to inform decomposition — WHERE determines target environment and file scope per unit, HOW constrains tech stack and approach, WHEN determines ordering and dependencies. For each unit-work define: CONTRACT: A → B | P, Clarity %: 0-100, Unclear: what is ambiguous if < 100%, Tags: 1-3 tags in {verb-ing}-{object} format derived from CONTRACT A/B. (* Tag format: /^[a-z]+-[a-z]+(-[a-z]+)*$/ *) (* Tags capture intent — what this unit does, searchable by /search-kg *) 4. Derive WP number and task_id: IF parent_wp = ⊥ → next WP-ST-{N} from existing files in work-plan/. IF parent_wp ≠ ⊥ → WP-ST-{parent_N}-{child_M}. Generate task_id: `uuidgen | cut -c1-8` → local uuid8. Write .gem-squared/work-plan/WP-ST-{id}.md: # WP-ST-{id}: {title} **STATUS:** PENDING | **STATE:** — | **task_id:** {task_id} **created_at:** {time_stamp} | **project_slug:** {project_slug} ## Objective {1-3 sentences synthesized from resolved 5W1H: WHAT is being done, WHY it matters, WHERE it applies. Include HOW/WHEN/WHO only if they constrain the work.} ## Unit-Works ### 1. {title} | STATUS: PENDING - A: {input state} - B: {output state} - P: {preconditions} - Clarity: {N}% - Unclear: {what is ambiguous} - Tags: [{verb-ing}-{object}, ...] (1-3 tags, searchable by /search-kg) - Result: (filled by /proceed-work) - State: (filled by /verify-work — SUCCESS or FAILURE) - Truth: (optional external verification — score% | Alignment | SPT | EEF) ### 2. {title} | STATUS: PENDING - A: / B: / P: / Clarity: / Unclear: - Result: - State: - Truth: (repeat for each unit-work, max 9) ## References - {patterns used} IF parent_wp ≠ ⊥ → update parent DECOMPOSITION section. Calculate avg_clarity. Output B. >> (* === Constraint === *) CONSTRAINT ≜ [ ⊢ NEVER execute work — planning and CONTRACT creation only, ⊢ NEVER exceed 9 sub-works per level — Miller's law ceiling, ⊢ NEVER decompose without resolving WHAT and WHERE — guessing scope produces bad CONTRACTs. WHERE = target + location, never tech stack, ⊢ NEVER ask about dimensions already clearly stated in work arg — extract, don't interrogate, ⊢ NEVER skip 5W1H for top-level WPs — sub-decompositions may inherit from parent, ⊢ NEVER decide recursion depth — human decides when clarity % is sufficient ] (* === Invariant === *) INV ≜ [ ⊢ Every WP Objective section reflects resolved 5W1H context — not just a rephrased work arg, ⊢ Every unit-work has a CONTRACT (A → B | P) — no uncontracted work, ⊢ Every unit-work has a clarity % — no unassessed scope, ⊢ Every unit-work has 1-3 Tags in {verb-ing}-{object} format — searchable by /search-kg, ⊢ Every unit-work has its own STATUS line (PENDING → IN_PROGRESS → COMPLETED/ABORTED), ⊢ Every unit-work has a Result field (empty until /proceed-work fills it), ⊢ WP-level STATUS derived from unit statuses: all COMPLETED → COMPLETED, any IN_PROGRESS → IN_PROGRESS, ⊢ WP file is the source of truth, ⊢ task_id is local uuid8, ⊢ Child WPs reference parent, parent tracks children — tree is navigable ] (* === Pre-Execution Dialog === *) Ask_Human ≜ << (* Step 0: If work arg is empty or ⊥, ask for initial description. *) [field: "work", prompt: "What work needs to be planned?", required: ⊤, condition: work = ⊥] (* Step 1 (5W1H): After parsing work arg, ask only about MISSING/UNCLEAR dimensions. *) (* Show extracted values, then targeted questions for gaps. *) [field: "5w1h_gaps", prompt: "I extracted the following from your request: {show RESOLVED dimensions} Please clarify: {for each MISSING/UNCLEAR required dimension: targeted question}", required: ⊤, condition: ∃ required dimension ∈ {WHAT, WHERE, WHY} that is MISSING ∨ UNCLEAR] >> (* === Post-Execution Routing === *) Routing ≜ [ avg_clarity ≥ 70 → /proceed-work (clear enough to execute), avg_clarity < 70 → suggest further decomposition or ask human for clarification, parent_wp ≠ ⊥ → return to parent context ]