Refactor doc spec guidance and remove step-level quality criteria#185
Merged
Refactor doc spec guidance and remove step-level quality criteria#185
Conversation
- Remove quality_criteria from define step in job.yml since output quality is covered by the doc_spec reference - Add guidance that doc spec criteria should focus on output requirements, not process; step-level quality_criteria should be process-only and minimized - Delete doc_spec.md.example files and update references to use .deepwork/doc_specs/job_spec.md as the canonical example - Remove redundant Quality Criteria section from define.md instruction files https://claude.ai/code/session_01V4ubYEhRcUJmCbEntzrzMC
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR clarifies the distinction between doc spec quality criteria (which define output document requirements) and step-level quality criteria (which define process requirements). It removes redundant step-level quality criteria from the
definestep in the deepwork_jobs job, since those requirements are now covered by the job.yml doc spec.Key Changes
Clarified doc spec quality criteria guidance: Added explicit documentation that doc spec quality criteria should focus on the output document itself, not the process of creating it. This prevents confusion and reduces duplication.
Removed step-level quality criteria from define step: Deleted 14 quality criteria from the
definestep in job.yml, as these are now properly covered by the job.yml doc spec. This follows the new guidance that step-level criteria should only be used for essential process requirements (e.g., "must use specific tool").Removed step-level quality criteria from define.md: Deleted the "Quality Criteria" section at the end of the define step documentation, which was redundant with the doc spec validation.
Updated doc spec example reference: Changed references from the template example file (
doc_spec.md.example) to the actual job.yml doc spec (.deepwork/doc_specs/job_spec.md) as the canonical example, making it more practical and real-world.Removed example template file: Deleted
doc_spec.md.example(AWS spending report example) since the job.yml doc spec now serves as the primary reference example.Updated architecture documentation: Removed reference to the deleted example file from the directory structure documentation.
Implementation Details
The changes apply consistently across multiple locations:
.claude/skills/deepwork_jobs.define/SKILL.md.deepwork/jobs/deepwork_jobs/job.yml.deepwork/jobs/deepwork_jobs/steps/define.md.gemini/skills/deepwork_jobs/define.tomlsrc/deepwork/standard_jobs/deepwork_jobs/job.ymlsrc/deepwork/standard_jobs/deepwork_jobs/steps/define.mddoc/architecture.mdThis refactoring reduces cognitive load by establishing a clear separation of concerns: doc specs handle output quality validation, while step-level criteria are reserved for process-specific requirements.
https://claude.ai/code/session_01V4ubYEhRcUJmCbEntzrzMC