diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index a6ec07d3..e13d2ac9 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.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. diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 1cb38621..4343cbda 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.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." diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index f94bee50..c22d3254 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.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 diff --git a/.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example b/.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example deleted file mode 100644 index 0e072048..00000000 --- a/.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example +++ /dev/null @@ -1,86 +0,0 @@ ---- -name: "Monthly AWS Spending Report" -description: "A Markdown summary of AWS spend across accounts for finance and engineering leadership" -path_patterns: - - "finance/aws-reports/*.md" - - "reports/aws/*.md" -target_audience: "Finance team and Engineering leadership" -frequency: "Monthly, following AWS invoice arrival" -quality_criteria: - - name: Executive Summary - description: Must include a 2-3 sentence summary of total spend, month-over-month change percentage, and top cost driver - - name: Visualization - description: Must include at least one Mermaid.js chart showing spend breakdown by service (pie chart) or trend over time (line chart) - - name: Variance Analysis - description: Must compare current month against previous month with percentage changes for top 5 services - - name: Cost Attribution - description: Must break down costs by team/project using AWS tags where available - - name: Action Items - description: Must include 2-3 specific, actionable recommendations for cost optimization ---- - -# Monthly AWS Spending Report: [Month, Year] - -## Executive Summary - -[2-3 sentences summarizing: -- Total spend this month -- Percentage change from last month -- The primary cost driver] - -## Spend Overview - -### Total Spend by Service - -```mermaid -pie title AWS Spend by Service - "EC2" : 45 - "RDS" : 25 - "S3" : 15 - "Lambda" : 10 - "Other" : 5 -``` - -### Month-over-Month Trend - -```mermaid -xychart-beta - title "Monthly AWS Spend Trend" - x-axis [Jan, Feb, Mar, Apr, May, Jun] - y-axis "Spend ($K)" 0 --> 100 - line [45, 48, 52, 49, 55, 58] -``` - -## Variance Analysis - -| Service | Last Month | This Month | Change | % Change | -|---------|-----------|------------|--------|----------| -| EC2 | $X,XXX | $X,XXX | +$XXX | +X.X% | -| RDS | $X,XXX | $X,XXX | -$XXX | -X.X% | -| S3 | $X,XXX | $X,XXX | +$XXX | +X.X% | -| Lambda | $X,XXX | $X,XXX | +$XXX | +X.X% | -| Other | $X,XXX | $X,XXX | +$XXX | +X.X% | - -## Cost Attribution by Team - -| Team/Project | Spend | % of Total | -|--------------|-------|------------| -| Platform | $X,XXX | XX% | -| Data | $X,XXX | XX% | -| Product | $X,XXX | XX% | -| Shared | $X,XXX | XX% | - -## Recommendations - -1. **[Action Item 1]**: [Specific recommendation with expected savings] -2. **[Action Item 2]**: [Specific recommendation with expected savings] -3. **[Action Item 3]**: [Specific recommendation with expected savings] - -## Appendix - -### Data Sources -- AWS Cost Explorer -- AWS Tags: team, project, environment - -### Report Methodology -[Brief explanation of how costs are calculated and attributed] diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 745062f3..872fa4dc 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.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. diff --git a/doc/architecture.md b/doc/architecture.md index cafd92c3..879481e3 100644 --- a/doc/architecture.md +++ b/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/ diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 1cb38621..4343cbda 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/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." diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index f94bee50..c22d3254 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/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 diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/doc_spec.md.example b/src/deepwork/standard_jobs/deepwork_jobs/templates/doc_spec.md.example deleted file mode 100644 index 0e072048..00000000 --- a/src/deepwork/standard_jobs/deepwork_jobs/templates/doc_spec.md.example +++ /dev/null @@ -1,86 +0,0 @@ ---- -name: "Monthly AWS Spending Report" -description: "A Markdown summary of AWS spend across accounts for finance and engineering leadership" -path_patterns: - - "finance/aws-reports/*.md" - - "reports/aws/*.md" -target_audience: "Finance team and Engineering leadership" -frequency: "Monthly, following AWS invoice arrival" -quality_criteria: - - name: Executive Summary - description: Must include a 2-3 sentence summary of total spend, month-over-month change percentage, and top cost driver - - name: Visualization - description: Must include at least one Mermaid.js chart showing spend breakdown by service (pie chart) or trend over time (line chart) - - name: Variance Analysis - description: Must compare current month against previous month with percentage changes for top 5 services - - name: Cost Attribution - description: Must break down costs by team/project using AWS tags where available - - name: Action Items - description: Must include 2-3 specific, actionable recommendations for cost optimization ---- - -# Monthly AWS Spending Report: [Month, Year] - -## Executive Summary - -[2-3 sentences summarizing: -- Total spend this month -- Percentage change from last month -- The primary cost driver] - -## Spend Overview - -### Total Spend by Service - -```mermaid -pie title AWS Spend by Service - "EC2" : 45 - "RDS" : 25 - "S3" : 15 - "Lambda" : 10 - "Other" : 5 -``` - -### Month-over-Month Trend - -```mermaid -xychart-beta - title "Monthly AWS Spend Trend" - x-axis [Jan, Feb, Mar, Apr, May, Jun] - y-axis "Spend ($K)" 0 --> 100 - line [45, 48, 52, 49, 55, 58] -``` - -## Variance Analysis - -| Service | Last Month | This Month | Change | % Change | -|---------|-----------|------------|--------|----------| -| EC2 | $X,XXX | $X,XXX | +$XXX | +X.X% | -| RDS | $X,XXX | $X,XXX | -$XXX | -X.X% | -| S3 | $X,XXX | $X,XXX | +$XXX | +X.X% | -| Lambda | $X,XXX | $X,XXX | +$XXX | +X.X% | -| Other | $X,XXX | $X,XXX | +$XXX | +X.X% | - -## Cost Attribution by Team - -| Team/Project | Spend | % of Total | -|--------------|-------|------------| -| Platform | $X,XXX | XX% | -| Data | $X,XXX | XX% | -| Product | $X,XXX | XX% | -| Shared | $X,XXX | XX% | - -## Recommendations - -1. **[Action Item 1]**: [Specific recommendation with expected savings] -2. **[Action Item 2]**: [Specific recommendation with expected savings] -3. **[Action Item 3]**: [Specific recommendation with expected savings] - -## Appendix - -### Data Sources -- AWS Cost Explorer -- AWS Tags: team, project, environment - -### Report Methodology -[Brief explanation of how costs are calculated and attributed]