Imported from Sighthesia/just-demand (.agents/skills/just-demand-intake/SKILL.md). Install upstream with npx skills add Sighthesia/just-demand --skill just-demand-intake. Copyright stays with the author.

Workflow Intake

Clarify the user's need before exposing workflow mechanics.

Core Rules

• Focus on the user's described outcome, expected behavior, anti-outcomes, constraints, and tradeoffs.
• Use socratic-clarification for progressive questioning before shaping new or ambiguous work.
• Do not outrank socratic-clarification. Intake starts after clarification has established the intended effect and direction for the current turn.
• When a later turn pivots from Q&A into a concrete request, bug, correction, or mismatch, route through socratic-clarification before intake.
• Keep the turn user-understandable, but do not use brevity as a reason to skip material uncertainty.
• Prefer the question tool for grouped decisions, approvals, and boundary capture when the answer can be expressed as concise options. Use free-text only for phenomena, nuanced descriptions, or answers that cannot be safely reduced to options.
• Do not discuss task packages, repo maps, JSONL, context injection, or subagent mechanics unless the user is explicitly designing those mechanisms.
• Treat intake as guidance; runtime plugins still enforce the workflow-entry gate for concrete requests without an active task.
• In no-plugin fallback mode, intake is the required next step after approved clarification when no formal task exists. Persist the approval in the formal task, then continue execution without asking again.

Process

1. Restate the user's goal and suspected anti-outcome.
2. Identify the requirement type: UI, workflow, bugfix, architecture, docs, research, or implementation.
3. Extract what the user already specified.
4. Apply the final artifact from socratic-clarification when present.
5. Record confirmed expectations, remaining gaps, and non-blocking questions.
6. Promote to a formal work item only after required fields and approval are present.

When clarification used bounded project discovery, record the user-approved effects and boundaries rather than copying a technical inventory into the intake. Files, modules, components, parameters, and evidence sources may support Touchpoints, Decisions, and validation, but they are not user requirements unless the user explicitly made them constraints.

If plugins are unavailable, disabled, or unstable, self-enforce this transition: after clarification approval, create/promote the intake before any write tool or execution subagent. Skill-only fallback is best-effort and cannot hard-block tools, so do not rely on a later plugin rejection to catch skipped intake.

Record clarification in user-language buckets that can later become task data:

• expected behavior
• actual behavior
• reproduction
• scope
• blocking questions
• non-blocking questions

Treat blocking questions as promotion blockers. Non-blocking questions may stay open if execution can still proceed safely.

Final Artifact Requirements

For design and implementation work, the intake must include the final artifact before promotion:

• Decision Card: first-screen, user-facing summary with one-sentence intent, recommended default, reason, and the user's expected action
• User Action: what the user needs to do next, or "no action needed"
• Recommended Default: the path the agent recommends if the user does not care
• Option Matrix: compact comparison of real alternatives by best-for, pros, cons, and failure mode
• Final Expected Effect: user-visible outcome in user language; this is a first-screen field, not an execution note
• Approach Options: 2-3 approaches with pros, cons, and practical failure modes; for UI/interaction work these must be meaningful user-visible alternatives, not placeholders
• Chosen Approach: selected approach with brief rationale
• Final Implementation Plan: agent-owned ordered engineering steps including verification; it does not need a separate user approval after the expected effect, boundaries, and material approach are approved
• Minimum Viable Knowledge: one-sentence explanations for unfamiliar terms or tradeoffs the user needs to decide
• Touchpoints: short concrete files/modules/components when known, plus explicit exclusions; this complements the formal Scope field and keeps user-facing scope readable
• Visible Acceptance: what the user can see, feel, or operate to confirm the result; routine tests/build/lint are mandatory agent work and should not dominate the first-screen approval card unless they fail or need user action
• Visible Side Effect: expected screen or operational side effects, not alternate unchosen approaches
• Diagram Intent: for flowcharts, architecture diagrams, state diagrams, data-flow/API diagrams, or other explanatory diagrams, what the diagram is meant to communicate
• Diagram Acceptance: what the user should be able to identify from the diagram, such as entry points, branches, boundaries, owners, states, transitions, sources, transforms, or destinations
• Expression Side Effect: what the diagram emphasizes, collapses, hides, or intentionally omits
• Validation: engineering checks and review steps for the task record or final report, secondary to visible acceptance in user-facing approval cards
• Validation Card: concise observable checks the user can scan before approval
• Diagram: small Mermaid or ASCII diagram when UI, workflow, state, process, or data shape would otherwise be ambiguous
• Confidence: high, medium, or low when it helps calibrate trust
• Escalation Reason: why this needs user input instead of safe agent decision
• Approval: explicit user approval of the final artifact

Promotion is blocked for design/implementation tasks when Final Expected Effect, Chosen Approach, Final Implementation Plan, or Approval are missing.

The first-screen user-facing fields are Decision Card, Final Expected Effect, Visible Acceptance, and Visible Side Effect. The remaining sections support execution and review, but they should not make the user feel like they are writing the implementation plan for us.

Blocking Questions Policy

A question is blocking when guessing the answer could change implementation path, validation criteria, user-facing behavior, or acceptable scope. Blocking questions include unresolved choices about expected behavior, actual behavior, reproduction conditions, affected scope, anti-outcomes, data loss/risk tolerance, or which tradeoff the user prefers.

Do not demote a question to non-blocking just because a likely answer exists. Only proceed without asking when the user already answered it, the repository has an explicit durable decision, or the implementation is safely reversible and user-visible behavior will not change.

Question Threshold

Ask implementation questions only when they affect:

• Product behavior or user-visible outcomes
• Architecture decisions or module boundaries
• Compatibility with existing systems or data
• Security, cost, or long-term maintenance

Do not ask about implementation details that are purely engineering preferences when they do not affect the above categories.

Intake Recording Shape

When socratic-clarification has produced a final artifact, record it in this shape:

Decision Card: <intent, recommended default, reason, user action>
User Action: <approve / choose / correct / no action needed>
Recommended Default: <agent's recommended path>
Option Matrix: <real alternatives by best-for, pros, cons, failure mode>
Final Expected Effect: <user-visible outcome>
Touchpoints: <short concrete files/modules/components when known, plus explicit exclusions>
Approach Options: <2-3 options with pros, cons, and failure modes>
Chosen Approach: <selected approach and rationale>
Final Implementation Plan: <ordered implementation and verification steps>
Minimum Viable Knowledge: <plain-language terms needed for the decision>
Visible Acceptance: <visible or operational checks the user can evaluate>
Visible Side Effect: <expected screen/operational side effects, or none>
Diagram Intent: <what an explanatory diagram is meant to communicate, if applicable>
Diagram Acceptance: <what the user can identify from the diagram, if applicable>
Expression Side Effect: <what the diagram emphasizes, collapses, hides, or intentionally omits>
Validation: <how the result will be checked>
Validation Card: <3-5 quick checks for user approval>
Diagram: <small Mermaid/ASCII diagram, or "not needed">
Confidence: <high|medium|low when useful>
Escalation Reason: <why user input is needed, or "none">
Approval: <explicit user approval or authorization>

Avoid vague placeholders:

Approved.
TBD.
Do the obvious thing.

Intake Recovery Shortcuts

create-intake only creates .just-demand/state/intake/<intake-id>.md. Before promotion, keep working in that same file.

Recovery recipe after create-intake:

1. Reopen the same intake markdown file; do not create a replacement intake.
2. Replace placeholders with the approved clarification artifact.
3. Keep unresolved items in ## Blocking Questions; clear or move them only when resolved.
4. Promote only after the required sections below are no longer empty.

Hard promotion gates by work shape:

• design/implementation: ## Scope, ## Final Expected Effect, ## Chosen Approach, ## Final Implementation Plan, ## Approval
• bug/mismatch: ## Scope, ## Expected Behavior, ## Actual Behavior, ## Reproduction

## Decision Card, ## User Action, ## Recommended Default, ## Option Matrix, ## Touchpoints, ## Approach Options, ## Minimum Viable Knowledge, ## Visible Acceptance, ## Visible Side Effect, ## Diagram Intent, ## Diagram Acceptance, ## Expression Side Effect, ## Validation, ## Validation Card, ## Diagram, ## Confidence, ## Escalation Reason, ## Current Understanding, ## Anti-Outcome, ## Decisions, and open-question sections should also be updated when the clarification artifact provides them, but the fields above are the runtime hard gates.

Recovery recipe after failed promote:

1. Read the error text and note each named missing field or remaining blocker.
2. Update that same intake markdown file; do not touch task.json and do not create a second intake.
3. Fill the named sections from approved user intent; ask instead of guessing.
4. Clear ## Blocking Questions only when each blocking item is actually resolved.
5. Rerun the same just-demand . promote ... command.

Questioning Patterns

Bug, regression, or expected-vs-actual mismatch

Drive toward this shape:

Expected behavior: what should happen.
Actual behavior: what happens instead.
Reproduction: when or how it shows up.
Scope: who, what path, or which environments are affected.
Blocking questions: anything that prevents safe implementation.

Preferred prompts:

• "What did you expect to happen here?"
• "What happens now instead?"
• "Can you reproduce it reliably, and if so with which steps or conditions?"
• "Is this isolated or does it affect multiple paths/users/environments?"
• "Which missing detail would make us likely fix the wrong thing?"

For expected-vs-actual mismatches, do not make the user compose the deviation description. Default to leading with the two-stage option flow from socratic-clarification (Proactive Deviation Options): Stage 1 options to locate the deviation dimension, Stage 2 "currently X, want Y or Z" contrast options to pin the target state. Reserve free-text for reproduction and other open-ended phenomena.

For visual or interaction mismatches, record the solution shape explicitly when it affects the user-visible result. At minimum, consider:

• containment: clip, hide, mask, or delay drawing
• synchronized entrance: foreground follows the container's expansion, anchor, direction, or timing
• layout/reflow: spacing, anchoring, available size, or row reveal changes so content naturally fits

If the user objects to the feel of a fix, such as "裁剪效果不好" or "not synchronized", treat that as approach drift. The next intake/update should choose a new solution shape instead of continuing the same patch family.

Feature, workflow, or implementation request

Drive toward this shape:

Desired outcome: what should be true when done.
Scope: what is in and out.
Anti-outcome: what would feel wrong even if technically complete.
Blocking questions: unresolved choices that would change the implementation path.
Non-blocking questions: polish or preference details that can remain open.

Preferred prompts:

• "What should a successful result let you do that you cannot do now?"
• "What is the smallest acceptable scope for this pass?"
• "What should we explicitly avoid changing?"
• "Which choice would materially change the implementation path if guessed wrong?"
• "Which details are nice-to-have and can stay open until execution?"

Default to this low-reading-cost shape before asking the user to make a tradeoff; keep it readable as a recommendation block, not a spec template. Do not surface internal workflow labels like Decision card on the first screen.

Recommendation:
- Intent: <one sentence>
- Recommended default: <what the agent recommends>
- Why: <one practical reason>
- User action: approve, choose another option, or correct the intent
- Confidence: <high|medium|low when useful>
- Escalation reason: <why the user must decide, or none>

Option matrix:
| Option | Best for | Pros | Cons | Failure mode |

Minimum viable knowledge:
- <term>: <one sentence, only if needed>

For UI/layout/animation work, use a visible-effect card instead of a generic engineering-plan card:

Recommended: <one sentence describing the visible effect>

Current:
+-- <component/region> h=<current height> --+
| <current visible problem>                  |
+--------------------------------------------+

Target:
+-- <component/region> h=<target/content> ---+
| padTop=<value or existing variable>         |
| <primary content>                           |
| <secondary/revealed content>                |
| padBottom=<value or existing variable>      |
+--------------------------------------------+
<parent or surrounding region effect>

Touchpoints: `<file/module>` and `<component>`; not changing <explicit exclusion>.
Quick checks:
- <observable checks; routine tests/build/lint are agent obligations and can be moved to optional detail unless failed>