workflow-clarify

Workflow clarify

Turn a request into a behavior agreement the user confirms. Read the code first, then ask only what the code can't answer. No tickets, no code.

Read shared policies from ../workflow/ from this SKILL.md; if it's missing, stop and say so. Never use a workflow copy from another skills root. Its SKILL.md "Always" list applies here too (end every turn with the state line).

Before you start, check: rules are READY, or a recorded LIMITED_EXCEPTION covers this phase within its limits (workflow/RULES.md); the task is found and checkpointed (workflow/TASK-FOLDER.md), or the router left only its identity open: then ask "separate task or revision?" as Q1 of your first round, saying a separate task is best in a fresh chat; word the other questions so they hold for either answer, save the round as TASK-FOLDER.md's "identity pending" row says, and never ask it alongside approvals; the request is real work, not explain-only or a lightweight edit. If an agreement already covers this revision, go to workflow-specify. Application UI, meaning anything a user sees on screen (order, text, which rows or items show, layout, not only styling): first read ../ui-design/SKILL.md and ../rule-maker/rules/design.md, then trace. Options you offer never include new CSS, not even as a one-off exception.

1. Trace the journeys

A journey is one actor getting one outcome: trigger → steps → what they see. For each actor the request touches, trace in the code and record in FINDINGS (J-IDs, E-IDs):

1. Owner and callers: the code that owns the behavior, every other caller or entry point that reaches it, and the data and settings it reads. A caller no journey explains is a question.
2. Failures: what the actor sees on bad input, missing permission, offline or failed dependency, timeout, cancel, retry.
3. Compatibility: saved data, old callers, public interfaces, versions; whether the change extends or replaces what exists.
4. State and timing: remembered after closing or across devices; applies now or on the next action.
5. Limits: allowed dependencies or cost, target environments, privacy, stated exclusions.
6. Screen (UI only): each new element, the existing one it mirrors (file:line, tag, classes) and what python -X utf8 -I ../ui-design/scripts/class_rules.py <project-root> <classes> prints. A [needs context] rule, or a layout difference shown by --compare <from-parent> <into-parent>, means no match: ask design.md rule 4's question.

How to read code and record evidence: workflow/GROUNDING.md.

Done when every journey's owner and callers are traced, or the missing access is recorded. Trace what a question depends on before asking it. Ask direction or access blockers at once and keep tracing the rest.

2. Grill

Read ../grilling/SKILL.md now, before writing any question, and run it on what step 1 found; asking without it skips the decision check.

Done when its stop rules hold ("Break it before stopping").

3. Write the agreement

Write ## Agreement in PLAN with workflow/scripts/record.py replace-section (workflow/WRITING.md rules):

• requirements (R-IDs), each with where it came from;
• what happens for each actor, including failures;
• what stays the same, and what is not included;
• acceptance (A-IDs) as things someone can observe;
• assumptions the user can reject, and choices deferred and by whom.

Describe behavior and acceptance; tickets, implementation file lists and test commands wait for workflow-specify.

4. Gate one

Summarize the agreement in chat in plain words: what happens for each actor, what stays the same, what is excluded, which assumptions they can reject, and the PLAN path. Then ask:

"Does this describe what should be built? Agree to it, or tell me what to change. Agreeing lets me write the detailed plan; no code changes until you approve that plan."

STOP. Answering grilling, silence or a generic "go" is not agreement. Never invite approval of a plan the user hasn't seen, and never borrow shortcuts from other tasks or earlier revisions.

When nothing is open and the change is small (workflow/VISUAL-REVIEW.md "Both gates in one message"), don't ask anything yet: invoke workflow-specify now. It writes the tickets and the HTML report and asks for both gates in one message. Clarify never asks for plan approval itself. An explicit yes to both, even in a later session, records both lines; continue with workflow-execute.

Record the answer in the checkpoint Agreement line (refreshing its next action) and DECISIONS: agreed (revision, date), partially agreed (reopened items go back to step 2), rejected, or an explicit waiver with its scope. Gate rules: workflow/VISUAL-REVIEW.md.

Next

• Agreed or waived: workflow-specify.
• Research: stop with findings and open choices written down. Plan-only: continue through workflow-specify, then stop; code needs an implementation request too.
• Blocked: record the blocking question or missing access, and what can still proceed.

A later change comes back here for the affected items only; the rest keeps its agreement.