Standardize on 'ask structured questions' phrasing

Update all job definitions and step instructions to explicitly use
the phrase "ask structured questions" when referring to gathering
user input. This ensures consistency across all DeepWork jobs.

Changes:
- deepwork_jobs v0.5.0: Updated description, define.md, implement.md,
  and quality criteria hooks to use "ask structured questions"
- deepwork_policy v0.2.0: Updated define.md to use phrase
- Added quality criteria hooks to verify phrase usage
- implement.md now instructs agents to use phrase in generated instructions

Author: claude

.claude/commands/deepwork_jobs.define.md

@@ -11,13 +11,14 @@ hooks:
 
             Verify the job.yml output meets ALL quality criteria before completing:
 
-            1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
-            2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
-            3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
-            4. **Concise Summary**: Is the summary under 200 characters and descriptive?
-            5. **Rich Description**: Does the description provide enough context for future refinement?
-            6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
-            7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
+            1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions?
+            2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input?
+            3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
+            4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
+            5. **Concise Summary**: Is the summary under 200 characters and descriptive?
+            6. **Rich Description**: Does the description provide enough context for future refinement?
+            7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
+            8. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
 
             If ANY criterion is not met, continue working to address it.
             If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
@@ -47,7 +48,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul
 workflows and learn from running them.
 
 The `define` command guides you through an interactive process to create a new job by
-asking detailed questions about your workflow, understanding each step's inputs and outputs,
+asking structured questions about your workflow, understanding each step's inputs and outputs,
 and generating all necessary files.
 
 The `learn` command reflects on conversations where DeepWork jobs were run, identifies
@@ -66,13 +67,15 @@ Create a `job.yml` specification file that defines the structure of a new DeepWo
 
 ## Task
 
-Guide the user through defining a job specification by asking clarifying questions. **Do not attempt to create the specification without first fully understanding the user's needs.**
+Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.**
+
+**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices.
 
 The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`).
 
 ### Step 1: Understand the Job Purpose
 
-Start by asking questions to understand what the user wants to accomplish:
+Start by asking structured questions to understand what the user wants to accomplish:
 
 1. **What is the overall goal of this workflow?**
    - What complex task are they trying to accomplish?
@@ -91,7 +94,7 @@ Start by asking questions to understand what the user wants to accomplish:
 
 ### Step 2: Define Each Step
 
-For each major phase they mentioned, ask detailed questions:
+For each major phase they mentioned, ask structured questions to gather details:
 
 1. **Step Purpose**
    - What exactly does this step accomplish?
@@ -152,7 +155,7 @@ After gathering information about all steps:
 
 For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met.
 
-**Ask the user about quality validation:**
+**Ask structured questions about quality validation:**
 - "Are there specific quality criteria that must be met for this step?"
 - "Would you like the agent to validate its work before completing?"
 - "What would make you send the work back for revision?"
@@ -341,11 +344,11 @@ Run `/deepwork_jobs.implement` to generate the instruction files for each step b
 ## Important Guidelines
 
 1. **Focus on specification only** - Don't create instruction files yet
-2. **Ask clarifying questions** - Never skip the discovery phase
+2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool
 3. **Rich context in description** - This helps with future refinement
 4. **Validate understanding** - Summarize and confirm before creating
 5. **Use examples** - Help users understand what good specifications look like
-6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed
+6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed
 
 ## Validation Rules
 
@@ -379,6 +382,7 @@ After creating the file:
 
 ## Quality Criteria
 
+- Asked structured questions to fully understand user requirements
 - User fully understands what job they're creating
 - All steps have clear inputs and outputs
 - Dependencies make logical sense
@@ -425,13 +429,14 @@ This step uses an iterative quality validation loop. After completing your work,
 ### Quality Criteria
 Verify the job.yml output meets ALL quality criteria before completing:
 
-1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
-2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
-3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
-4. **Concise Summary**: Is the summary under 200 characters and descriptive?
-5. **Rich Description**: Does the description provide enough context for future refinement?
-6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
-7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
+1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions?
+2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input?
+3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
+4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
+5. **Concise Summary**: Is the summary under 200 characters and descriptive?
+6. **Rich Description**: Does the description provide enough context for future refinement?
+7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
+8. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
 
 If ANY criterion is not met, continue working to address it.
 If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.

.claude/commands/deepwork_jobs.implement.md

@@ -16,9 +16,10 @@ hooks:
             3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
             4. **Output Examples**: Does each instruction file show what good output looks like?
             5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
-            6. **Sync Complete**: Has `deepwork sync` been run successfully?
-            7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-            8. **Policies Considered**: Have you thought about whether policies would benefit this job?
+            6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
+            7. **Sync Complete**: Has `deepwork sync` been run successfully?
+            8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
+            9. **Policies Considered**: Have you thought about whether policies would benefit this job?
                - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
                - Not every job needs policies - only suggest when genuinely helpful.
 
@@ -50,7 +51,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul
 workflows and learn from running them.
 
 The `define` command guides you through an interactive process to create a new job by
-asking detailed questions about your workflow, understanding each step's inputs and outputs,
+asking structured questions about your workflow, understanding each step's inputs and outputs,
 and generating all necessary files.
 
 The `learn` command reflects on conversations where DeepWork jobs were run, identifies
@@ -138,6 +139,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw
 4. **Explain the "why"** - Help the user understand the step's role in the workflow
 5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones
 6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks
+7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions"
 
 ### Handling Stop Hooks
 
@@ -300,6 +302,7 @@ Before marking this step complete, ensure:
 - Instructions are specific and actionable
 - Output examples are provided in each instruction file
 - Quality criteria defined for each step
+- Steps with user inputs explicitly use "ask structured questions" phrasing
 - Sync completed successfully
 - Commands available for use
 - Thoughtfully considered relevant policies for the job domain
@@ -349,9 +352,10 @@ Verify the implementation meets ALL quality criteria before completing:
 3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
 4. **Output Examples**: Does each instruction file show what good output looks like?
 5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
-6. **Sync Complete**: Has `deepwork sync` been run successfully?
-7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-8. **Policies Considered**: Have you thought about whether policies would benefit this job?
+6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
+7. **Sync Complete**: Has `deepwork sync` been run successfully?
+8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
+9. **Policies Considered**: Have you thought about whether policies would benefit this job?
    - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
    - Not every job needs policies - only suggest when genuinely helpful.
 

.claude/commands/deepwork_jobs.learn.md

@@ -50,7 +50,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul
 workflows and learn from running them.
 
 The `define` command guides you through an interactive process to create a new job by
-asking detailed questions about your workflow, understanding each step's inputs and outputs,
+asking structured questions about your workflow, understanding each step's inputs and outputs,
 and generating all necessary files.
 
 The `learn` command reflects on conversations where DeepWork jobs were run, identifies

.claude/commands/deepwork_policy.define.md

@@ -38,11 +38,13 @@ Create or update policy entries in the `.deepwork.policy.yml` file to enforce te
 
 ## Task
 
-Guide the user through defining a new policy by asking clarifying questions. **Do not create the policy without first understanding what they want to enforce.**
+Guide the user through defining a new policy by asking structured questions. **Do not create the policy without first understanding what they want to enforce.**
+
+**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices.
 
 ### Step 1: Understand the Policy Purpose
 
-Start by asking questions to understand what the user wants to enforce:
+Start by asking structured questions to understand what the user wants to enforce:
 
 1. **What guideline or constraint should this policy enforce?**
    - What situation triggers the need for action?
@@ -207,6 +209,7 @@ Create or update this file at the project root with the new policy entry.
 
 ## Quality Criteria
 
+- Asked structured questions to understand user requirements
 - Policy name is clear and descriptive
 - Trigger patterns accurately match the intended files
 - Safety patterns prevent unnecessary triggering

.deepwork/jobs/deepwork_jobs/job.yml

@@ -1,12 +1,12 @@
 name: deepwork_jobs
-version: "0.4.0"
+version: "0.5.0"
 summary: "DeepWork job management commands"
 description: |
   Core commands for managing DeepWork jobs. These commands help you define new multi-step
   workflows and learn from running them.
 
   The `define` command guides you through an interactive process to create a new job by
-  asking detailed questions about your workflow, understanding each step's inputs and outputs,
+  asking structured questions about your workflow, understanding each step's inputs and outputs,
   and generating all necessary files.
 
   The `learn` command reflects on conversations where DeepWork jobs were run, identifies
@@ -22,6 +22,8 @@ changelog:
     changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples"
   - version: "0.4.0"
     changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs"
+  - version: "0.5.0"
+    changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions"
 
 steps:
   - id: define
@@ -39,13 +41,14 @@ steps:
         - prompt: |
             Verify the job.yml output meets ALL quality criteria before completing:
 
-            1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
-            2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
-            3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
-            4. **Concise Summary**: Is the summary under 200 characters and descriptive?
-            5. **Rich Description**: Does the description provide enough context for future refinement?
-            6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
-            7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
+            1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions?
+            2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input?
+            3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
+            4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
+            5. **Concise Summary**: Is the summary under 200 characters and descriptive?
+            6. **Rich Description**: Does the description provide enough context for future refinement?
+            7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
+            8. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
 
             If ANY criterion is not met, continue working to address it.
             If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
@@ -71,9 +74,10 @@ steps:
             3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
             4. **Output Examples**: Does each instruction file show what good output looks like?
             5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
-            6. **Sync Complete**: Has `deepwork sync` been run successfully?
-            7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-            8. **Policies Considered**: Have you thought about whether policies would benefit this job?
+            6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
+            7. **Sync Complete**: Has `deepwork sync` been run successfully?
+            8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
+            9. **Policies Considered**: Have you thought about whether policies would benefit this job?
                - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
                - Not every job needs policies - only suggest when genuinely helpful.