|
| 1 | +job_definition_review: |
| 2 | + description: "Review job.yml, requirements.md, and step instructions for correctness, completeness, and coherence as a holistic workflow." |
| 3 | + match: |
| 4 | + include: |
| 5 | + - "job.yml" |
| 6 | + - "steps/*.md" |
| 7 | + - "requirements.md" |
| 8 | + review: |
| 9 | + strategy: matches_together |
| 10 | + instructions: | |
| 11 | + Review this DeepWork job definition (job.yml), its requirements (requirements.md), |
| 12 | + and its step instruction files (steps/*.md) holistically. Check that they form a |
| 13 | + coherent, well-structured workflow that an AI agent can execute reliably. |
| 14 | + |
| 15 | + ## Reference Material |
| 16 | + |
| 17 | + For reference on correct job structure and best practices, read the following files from your plugin: |
| 18 | + - `job.yml.template` — canonical job.yml structure with all supported fields |
| 19 | + - `job.yml.example` — a complete working example (competitive research job) |
| 20 | + - `step_instruction.md.template` — expected structure for step instruction files |
| 21 | + - `research_report_job_best_practices.md` — design patterns for report-type jobs |
| 22 | + |
| 23 | + ## What to Check |
| 24 | + |
| 25 | + ### 1. job.yml Structure |
| 26 | + - Has required fields: `name`, `version`, `summary`, `workflows`, `steps` |
| 27 | + - `name` is lowercase with underscores only |
| 28 | + - `summary` is concise (under 200 characters) and descriptive enough to let a user know what the job does |
| 29 | + - `version` follows semantic versioning (e.g., "1.0.0") |
| 30 | + - `common_job_info_provided_to_all_steps_at_runtime` provides useful shared context (problem domain, terminology, conventions, constraints) |
| 31 | + |
| 32 | + ### 2. Workflow Coherence |
| 33 | + - Each workflow's steps form a logical sequence toward a clear goal |
| 34 | + - Step dependencies are declared correctly (no missing or extraneous deps) |
| 35 | + - No circular dependencies exist |
| 36 | + |
| 37 | + ### 3. Input/Output Chain |
| 38 | + - Each step has at least one output |
| 39 | + - File inputs reference outputs from steps listed in that step's dependencies |
| 40 | + - `from_step` values match actual step IDs that produce the referenced file |
| 41 | + - The output chain creates a logical data flow through the workflow |
| 42 | + - Intermediate outputs that are not meant to be persisted should be in .deepwork/tmp (and the name should indicate that) |
| 43 | + - Final outputs follow project conventions (not hidden in dot-directories, descriptive names, appropriate use of subdirectories) |
| 44 | + |
| 45 | + ### 4. Step Instructions Match job.yml |
| 46 | + - Every step defined in job.yml has a corresponding instruction file |
| 47 | + - Step instruction content aligns with the step's described purpose |
| 48 | + - Instructions reference the correct input and output filenames from job.yml |
| 49 | + - Instructions do not duplicate content already in `common_job_info_provided_to_all_steps_at_runtime` |
| 50 | + - If there is duplicated content amongst the instruction files, it should be moved to `common_job_info_provided_to_all_steps_at_runtime` and removed from the instruction files |
| 51 | + - If there is content that is needed in multiple steps but not all, it should be moved to its own file and referenced in the steps |
| 52 | + |
| 53 | + ### 5. Quality Reviews |
| 54 | + - Steps with complex or final outputs have reviews defined |
| 55 | + - `run_each` values reference valid output names or `step` |
| 56 | + - Quality criteria are statements of expected state, not questions |
| 57 | + - `additional_review_guidance` is used when reviewers need context beyond the step's own output files (e.g., cross-referencing prior step outputs) |
| 58 | + - Steps with no meaningful quality checks use `reviews: []` |
| 59 | + |
| 60 | + ### 6. Step Instruction Quality |
| 61 | + - Each instruction file follows the structure and section headings defined in |
| 62 | + `step_instruction.md.template` for this job type. |
| 63 | + - The sections clearly communicate: what the step is trying to achieve, |
| 64 | + what the agent should do, what to produce (including format/examples), |
| 65 | + and how quality will be evaluated. |
| 66 | + - Instructions are specific and actionable, not generic placeholders |
| 67 | + - Output format sections show what good output looks like (examples or |
| 68 | + templates) |
| 69 | + - If the step gathers user input, instructions mention using structured |
| 70 | + questions (e.g., the AskUserQuestion tool) |
| 71 | + - Instructions explain how to use file inputs from prior steps and how the |
| 72 | + step's outputs will be consumed by later steps. |
| 73 | + |
| 74 | + ## Output Format |
| 75 | + |
| 76 | + - PASS: The job definition and step instructions are coherent and |
| 77 | + well-structured. |
| 78 | + - FAIL: List each issue with the specific file, the problem, and a |
| 79 | + suggested fix. |
| 80 | + additional_context: |
| 81 | + unchanged_matching_files: true |
0 commit comments