Refactor doc spec guidance and remove step-level quality criteria

.claude/skills/deepwork_jobs.define/SKILL.md

@@ -81,11 +81,16 @@ When creating a doc spec, gather the following information:
    - How often is it produced? (frequency)
 
 3. **Quality Criteria** (3-5 criteria, each with name and description)
+
+   **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve.
+
    Examples for a spending report:
    - **Visualization**: Must include charts showing spend breakdown by service
    - **Variance Analysis**: Must compare current month against previous with percentages
    - **Action Items**: Must include recommended cost optimization actions
 
+   **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible.
+
 4. **Document Structure**
    - What sections should it have?
    - Any required elements (tables, charts, summaries)?
@@ -96,7 +101,7 @@ Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`:
 
 **Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure.
 
-**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example` for a fully worked example.
+**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files).
 
 After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output.
 

.deepwork/jobs/deepwork_jobs/job.yml

@@ -55,20 +55,6 @@ steps:
       - file: job.yml
         doc_spec: .deepwork/doc_specs/job_spec.md
     dependencies: []
-    quality_criteria:
-      - "**User Understanding**: Did the agent fully understand the user's workflow by asking structured questions?"
-      - "**Structured Questions Used**: Did the agent ask structured questions (using the AskUserQuestion tool) to gather user input?"
-      - "**Document Detection**: For document-oriented workflows, did the agent detect patterns and offer doc spec creation?"
-      - "**doc spec Created (if applicable)**: If a doc spec was needed, was it created in `.deepwork/doc_specs/[doc_spec_name].md` with proper quality criteria?"
-      - "**doc spec References**: Are document outputs properly linked to their doc specs using `{file, doc_spec}` format?"
-      - "**Valid Against doc spec**: Does the job.yml conform to the job.yml doc spec quality criteria (valid identifier, semantic version, concise summary, rich description, complete steps, valid dependencies)?"
-      - "**Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?"
-      - "**Logical Dependencies**: Do step dependencies make sense and avoid circular references?"
-      - "**Concise Summary**: Is the summary under 200 characters and descriptive?"
-      - "**Rich Description**: Does the description provide enough context for future refinement?"
-      - "**Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?"
-      - "**File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?"
-
   - id: review_job_spec
     name: "Review Job Specification"
     description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification."

.deepwork/jobs/deepwork_jobs/steps/define.md

@@ -61,11 +61,16 @@ When creating a doc spec, gather the following information:
    - How often is it produced? (frequency)
 
 3. **Quality Criteria** (3-5 criteria, each with name and description)
+
+   **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve.
+
    Examples for a spending report:
    - **Visualization**: Must include charts showing spend breakdown by service
    - **Variance Analysis**: Must compare current month against previous with percentages
    - **Action Items**: Must include recommended cost optimization actions
 
+   **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible.
+
 4. **Document Structure**
    - What sections should it have?
    - Any required elements (tables, charts, summaries)?
@@ -76,7 +81,7 @@ Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`:
 
 **Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure.
 
-**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example` for a fully worked example.
+**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files).
 
 After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output.
 
@@ -385,13 +390,3 @@ After creating the file:
 2. Recommend that they review the job.yml file
 3. Tell them to run `/deepwork_jobs.review_job_spec` next
 
-## 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
-- Summary is concise and descriptive
-- Description provides rich context for future refinement
-- Specification is valid YAML and follows the schema
-- Ready for implementation step

.gemini/skills/deepwork_jobs/define.toml

@@ -81,11 +81,16 @@ When creating a doc spec, gather the following information:
    - How often is it produced? (frequency)
 
 3. **Quality Criteria** (3-5 criteria, each with name and description)
+
+   **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve.
+
    Examples for a spending report:
    - **Visualization**: Must include charts showing spend breakdown by service
    - **Variance Analysis**: Must compare current month against previous with percentages
    - **Action Items**: Must include recommended cost optimization actions
 
+   **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible.
+
 4. **Document Structure**
    - What sections should it have?
    - Any required elements (tables, charts, summaries)?
@@ -96,7 +101,7 @@ Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`:
 
 **Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure.
 
-**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example` for a fully worked example.
+**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files).
 
 After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output.
 

doc/architecture.md

@@ -68,8 +68,7 @@ deepwork/                       # DeepWork tool repository
 │       │   │   ├── job.yml
 │       │   │   ├── steps/
 │       │   │   └── templates/
-│       │   │       ├── doc_spec.md.template
-│       │   │       └── doc_spec.md.example
+│       │   │       └── doc_spec.md.template
 │       │   └── deepwork_rules/   # Rule management job
 │       │       ├── job.yml
 │       │       ├── steps/

src/deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -55,20 +55,6 @@ steps:
       - file: job.yml
         doc_spec: .deepwork/doc_specs/job_spec.md
     dependencies: []
-    quality_criteria:
-      - "**User Understanding**: Did the agent fully understand the user's workflow by asking structured questions?"
-      - "**Structured Questions Used**: Did the agent ask structured questions (using the AskUserQuestion tool) to gather user input?"
-      - "**Document Detection**: For document-oriented workflows, did the agent detect patterns and offer doc spec creation?"
-      - "**doc spec Created (if applicable)**: If a doc spec was needed, was it created in `.deepwork/doc_specs/[doc_spec_name].md` with proper quality criteria?"
-      - "**doc spec References**: Are document outputs properly linked to their doc specs using `{file, doc_spec}` format?"
-      - "**Valid Against doc spec**: Does the job.yml conform to the job.yml doc spec quality criteria (valid identifier, semantic version, concise summary, rich description, complete steps, valid dependencies)?"
-      - "**Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?"
-      - "**Logical Dependencies**: Do step dependencies make sense and avoid circular references?"
-      - "**Concise Summary**: Is the summary under 200 characters and descriptive?"
-      - "**Rich Description**: Does the description provide enough context for future refinement?"
-      - "**Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?"
-      - "**File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?"
-
   - id: review_job_spec
     name: "Review Job Specification"
     description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification."

src/deepwork/standard_jobs/deepwork_jobs/steps/define.md

@@ -61,11 +61,16 @@ When creating a doc spec, gather the following information:
    - How often is it produced? (frequency)
 
 3. **Quality Criteria** (3-5 criteria, each with name and description)
+
+   **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve.
+
    Examples for a spending report:
    - **Visualization**: Must include charts showing spend breakdown by service
    - **Variance Analysis**: Must compare current month against previous with percentages
    - **Action Items**: Must include recommended cost optimization actions
 
+   **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible.
+
 4. **Document Structure**
    - What sections should it have?
    - Any required elements (tables, charts, summaries)?
@@ -76,7 +81,7 @@ Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`:
 
 **Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure.
 
-**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example` for a fully worked example.
+**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files).
 
 After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output.
 
@@ -385,13 +390,3 @@ After creating the file:
 2. Recommend that they review the job.yml file
 3. Tell them to run `/deepwork_jobs.review_job_spec` next
 
-## 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
-- Summary is concise and descriptive
-- Description provides rich context for future refinement
-- Specification is valid YAML and follows the schema
-- Ready for implementation step