From 08129dbc17d4f207537aa19f65bb12aa04c945d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Jan 2026 22:10:44 +0000 Subject: [PATCH 1/3] Replace refine command with learn command for conversation-driven improvement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The learn command reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the appropriate working folder. Key features: - Analyzes conversation for DeepWork job executions - Classifies learnings as generalizable (→ instructions) or bespoke (→ AGENTS.md) - Uses file references in AGENTS.md to keep things in sync - Creates learning_summary.md documenting all changes Changes: - Removed refine step from deepwork_jobs - Added learn step with comprehensive instructions - Updated job version to 0.2.0 - Regenerated all command files --- .claude/commands/deepwork_jobs.define.md | 7 +- .claude/commands/deepwork_jobs.implement.md | 11 +- .claude/commands/deepwork_jobs.learn.md | 463 ++++++++++++++ .claude/commands/deepwork_jobs.refine.md | 595 ------------------ .deepwork/jobs/deepwork_jobs/job.yml | 41 +- .deepwork/jobs/deepwork_jobs/steps/learn.md | 314 +++++++++ .deepwork/jobs/deepwork_jobs/steps/refine.md | 447 ------------- .gemini/commands/deepwork_jobs/define.toml | 7 +- .gemini/commands/deepwork_jobs/implement.toml | 11 +- .gemini/commands/deepwork_jobs/learn.toml | 406 ++++++++++++ .../standard_jobs/deepwork_jobs/job.yml | 41 +- .../deepwork_jobs/steps/learn.md | 314 +++++++++ .../deepwork_jobs/steps/refine.md | 447 ------------- 13 files changed, 1561 insertions(+), 1543 deletions(-) create mode 100644 .claude/commands/deepwork_jobs.learn.md delete mode 100644 .claude/commands/deepwork_jobs.refine.md create mode 100644 .deepwork/jobs/deepwork_jobs/steps/learn.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/refine.md create mode 100644 .gemini/commands/deepwork_jobs/learn.toml create mode 100644 src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md delete mode 100644 src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md diff --git a/.claude/commands/deepwork_jobs.define.md b/.claude/commands/deepwork_jobs.define.md index 2030d982..b210991b 100644 --- a/.claude/commands/deepwork_jobs.define.md +++ b/.claude/commands/deepwork_jobs.define.md @@ -44,14 +44,15 @@ hooks: ## Job Overview Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and refine existing ones. +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, and generating all necessary files. -The `refine` command helps you modify existing jobs safely by understanding what you want -to change, validating the impact, and ensuring consistency across your workflow. +The `learn` command reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.claude/commands/deepwork_jobs.implement.md b/.claude/commands/deepwork_jobs.implement.md index b2c3d7e8..98d5c7d1 100644 --- a/.claude/commands/deepwork_jobs.implement.md +++ b/.claude/commands/deepwork_jobs.implement.md @@ -48,14 +48,15 @@ hooks: ## Job Overview Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and refine existing ones. +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, and generating all necessary files. -The `refine` command helps you modify existing jobs safely by understanding what you want -to change, validating the impact, and ensuring consistency across your workflow. +The `learn` command reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. ## Prerequisites @@ -578,13 +579,13 @@ After completing this step: 2. **Inform the user**: - Step 2 of 3 is complete - Outputs created: implementation_summary.md - - Ready to proceed to next step: `/deepwork_jobs.refine` + - Ready to proceed to next step: `/deepwork_jobs.learn` ## Next Step To continue the workflow, run: ``` -/deepwork_jobs.refine +/deepwork_jobs.learn ``` --- diff --git a/.claude/commands/deepwork_jobs.learn.md b/.claude/commands/deepwork_jobs.learn.md new file mode 100644 index 00000000..6352b632 --- /dev/null +++ b/.claude/commands/deepwork_jobs.learn.md @@ -0,0 +1,463 @@ +--- +description: Reflect on conversation to improve job instructions and capture learnings +hooks: + Stop: + - hooks: + - type: prompt + prompt: | + You must evaluate whether Claude has met all the below quality criteria for the request. + + ## Quality Criteria + + Verify the learning process meets ALL quality criteria before completing: + + 1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? + 2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? + 3. **Instructions Improved**: Were job instructions updated to address identified issues? + 4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? + 5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? + 6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? + 7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? + 8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? + + If ANY criterion is not met, continue working to address it. + If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. + + + ## Instructions + + Review the conversation and determine if ALL quality criteria above have been satisfied. + Look for evidence that each criterion has been addressed. + + If the agent has included `✓ Quality Criteria Met` in their response AND + all criteria appear to be met, respond with: {"ok": true} + + If criteria are NOT met AND the promise tag is missing, respond with: + {"ok": false, "reason": "Continue working. [specific feedback on what's wrong]"} +--- + +# deepwork_jobs.learn + +**Standalone command** in the **deepwork_jobs** job - can be run anytime + +**Summary**: DeepWork job management commands + +## Job Overview + +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, +and generating all necessary files. + +The `learn` command reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. + + + +## Instructions + +# Learn from Job Execution + +## Objective + +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. + +## Task + +Analyze the conversation history to extract learnings and improvements, then apply them appropriately: +- **Generalizable learnings** → Update job instruction files +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder + +### Step 1: Analyze Conversation for Job Executions + +1. **Scan the conversation** for DeepWork slash commands that were run + - Look for patterns like `/job_name.step_id` + - Identify which jobs and steps were executed + - Note the order of execution + +2. **Identify the working folder** + - Find where outputs were created during job execution + - This is typically specified in the job's working directory + - Common patterns: project root, `./output/`, or job-specific directories + +3. **If no job was specified**, ask the user: + - "Which DeepWork job would you like me to learn from?" + - List available jobs from `.deepwork/jobs/` + +### Step 2: Identify Points of Confusion and Inefficiency + +Review the conversation for: + +1. **Confusion signals** + - Questions the agent asked that shouldn't have been necessary + - Misunderstandings about what a step required + - Incorrect outputs that needed correction + - Ambiguous instructions that led to wrong interpretations + +2. **Inefficiency signals** + - Extra steps or iterations that were needed + - Information that had to be repeated + - Context that was missing from instructions + - Dependencies that weren't clear + +3. **Error patterns** + - Failed validations and why they failed + - Quality criteria that were misunderstood + - Edge cases that weren't handled + +4. **Success patterns** + - What worked particularly well + - Efficient approaches worth preserving + - Good examples that could be added to instructions + +### Step 3: Classify Learnings + +For each learning identified, determine if it is: + +**Generalizable** (should improve instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions in instructions +- Adds helpful examples or context +- Examples: + - "Step instructions should mention that X format is required" + - "Quality criteria should include checking for Y" + - "Add example of correct output format" + +**Bespoke** (should go in AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions or structure +- References specific files or paths +- Would not apply to other uses of this job +- Examples: + - "In this codebase, API endpoints are in `src/api/`" + - "This project uses camelCase for function names" + - "The main config file is at `config/settings.yml`" + +### Step 4: Update Job Instructions (Generalizable Learnings) + +For each generalizable learning: + +1. **Locate the instruction file** + - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` + +2. **Make targeted improvements** + - Add missing context or clarification + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria if needed + +3. **Preserve instruction structure** + - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) + - Add to appropriate sections rather than restructuring + - Maintain consistency with other steps + +4. **Track changes for changelog** + - Note what was changed and why + - Prepare changelog entry for job.yml + +### Step 5: Create/Update AGENTS.md (Bespoke Learnings) + +The AGENTS.md file captures project-specific knowledge that helps future agent runs. + +1. **Determine the correct location** + - Place AGENTS.md in the working folder where job outputs live + - This ensures the knowledge is available when working in that context + - If uncertain, place at the project root + +2. **Use file references where possible** + - Instead of duplicating information, reference source files + - This keeps AGENTS.md in sync as the codebase evolves + - Pattern: "See `path/to/file.ext` for [description]" + +3. **AGENTS.md structure**: + +```markdown +# Project Context for [Job Name] + +## Codebase Structure + + +- Project structure: See `README.md` for overview +- API documentation: See `docs/api.md` +- Configuration: See `config/README.md` + +## Conventions + +### Naming Conventions +- [Convention]: See example in `path/to/example.ext:LINE` + +### File Organization +- [Pattern]: Reference `path/to/pattern/` + +## Job-Specific Context + +### [Job Name] + +#### [Step Name] +- [Learning]: Reference `relevant/file.ext` +- [Context]: [Brief explanation with file reference] + +## Known Issues and Workarounds + +- [Issue]: [Workaround with file reference if applicable] + +## Last Updated +- Date: [YYYY-MM-DD] +- From conversation about: [Brief description] +``` + +4. **Writing entries** + - Be concise but specific + - Always prefer file references over inline content + - Use line numbers when referencing specific code: `file.ext:42` + - Group related learnings together + +### Step 6: Update Job Version and Changelog + +If instruction files were modified: + +1. **Bump version in job.yml** + - Patch version (0.0.x) for instruction improvements + - Minor version (0.x.0) if quality criteria changed + +2. **Add changelog entry** + ```yaml + - version: "[new_version]" + changes: "Improved [step] instructions based on execution learnings: [brief description]" + ``` + +### Step 7: Sync and Summarize + +1. **Run deepwork sync** (if instructions were modified) + ```bash + deepwork sync + ``` + +2. **Create learning_summary.md** in the working folder: + ```markdown + # Learning Summary + + ## Job Analyzed + - Job: [job_name] + - Steps executed: [list of steps] + + ## Generalizable Improvements Made + - [Step]: [What was improved] + + ## Bespoke Learnings Captured + - Location: [path to AGENTS.md] + - Entries added: [list of entries] + + ## Files Modified + - [List of files changed] + + ## Recommendations + - [Any additional suggestions] + ``` + +3. **Instruct user to reload** if commands were regenerated + +## File Reference Patterns + +When adding entries to AGENTS.md, prefer these patterns: + +**Good (references)**: +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` +``` + +**Avoid (duplicating)**: +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +- Error handling should use try/catch with custom error classes +- Configuration requires these fields: name, version, ... +``` + +## Quality Criteria + +- Conversation has been analyzed for job executions +- Points of confusion and inefficiency are identified +- Learnings are correctly classified (generalizable vs bespoke) +- Job instructions updated for generalizable improvements +- AGENTS.md created/updated with bespoke learnings +- File references used instead of duplicating content +- AGENTS.md is in the correct working folder +- learning_summary.md documents all changes +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.learn + +Claude: I'll analyze this conversation for learnings from DeepWork job executions. + +**Conversation Analysis** + +I found the following job executions: +1. `/competitive_research.identify_competitors` - Completed +2. `/competitive_research.research_competitors` - Completed with 2 iterations +3. `/competitive_research.comparative_analysis` - Completed + +**Identified Issues** + +1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. + +2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. + +**Classification** + +- Generalizable: Add pricing to research requirements in instructions +- Bespoke: This project focuses on B2B SaaS in the HR tech space + +**Actions Taken** + +1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: + - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements + - Added note about carrying forward industry context from previous step + +2. Created `./competitive_research_output/AGENTS.md`: + ```markdown + # Project Context for Competitive Research + + ## Job-Specific Context + + ### competitive_research + + #### Industry Focus + - Domain: B2B SaaS, HR Technology sector + - See `identify_competitors_output.md` for market definition + + #### Competitors Identified + - Reference: `competitor_list.md` for full details + + ## Last Updated + - Date: 2024-01-15 + - From conversation about: Initial competitive analysis run + ``` + +3. Updated job.yml version to 1.0.1 with changelog entry + +4. Ran `deepwork sync` + +**Summary** + +Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +``` + +## Handling Edge Cases + +**No job executions found**: +- Ask user which job they'd like to analyze +- Or offer to review available jobs + +**Multiple jobs executed**: +- Analyze each job separately +- Create separate AGENTS.md entries or files as appropriate + +**AGENTS.md already exists**: +- Read existing content +- Append new learnings to appropriate sections +- Update "Last Updated" section + +**No issues found**: +- Document what worked well +- Consider if any successful patterns should be added to instructions as examples + +**Sensitive information**: +- Never include secrets, credentials, or PII in AGENTS.md +- Reference config files instead of including values + + +## Inputs + +### User Parameters + +Please gather the following information from the user: +- **job_name**: Name of the job that was run (optional - will auto-detect from conversation) + + +## Work Branch Management + +All work for this job should be done on a dedicated work branch: + +1. **Check current branch**: + - If already on a work branch for this job (format: `deepwork/deepwork_jobs-[instance]-[date]`), continue using it + - If on main/master, create a new work branch + +2. **Create work branch** (if needed): + ```bash + git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d) + ``` + Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.) + +## Output Requirements + +Create the following output(s): +- `learning_summary.md` +Ensure all outputs are: +- Well-formatted and complete +- Ready for review or use by subsequent steps + +## Quality Validation Loop + +This step uses an iterative quality validation loop. After completing your work, stop hook(s) will evaluate whether the outputs meet quality criteria. If criteria are not met, you will be prompted to continue refining. + +### Quality Criteria +Verify the learning process meets ALL quality criteria before completing: + +1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? +2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? +3. **Instructions Improved**: Were job instructions updated to address identified issues? +4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? +5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? +6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? +7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? +8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? + +If ANY criterion is not met, continue working to address it. +If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. + + +### Completion Promise + +To signal that all quality criteria have been met, include this tag in your final response: + +``` +✓ Quality Criteria Met +``` + +**Important**: Only include this promise tag when you have verified that ALL quality criteria above are satisfied. The validation loop will continue until this promise is detected. + +## Completion + +After completing this step: + +1. **Verify outputs**: Confirm all required files have been created + +2. **Inform the user**: + - The learn command is complete + - Outputs created: learning_summary.md + - This command can be run again anytime to make further changes + +## Command Complete + +This is a standalone command that can be run anytime. The outputs are ready for use. + +Consider: +- Reviewing the outputs +- Running `deepwork sync` if job definitions were changed +- Re-running this command later if further changes are needed + +--- + +## Context Files + +- Job definition: `.deepwork/jobs/deepwork_jobs/job.yml` +- Step instructions: `.deepwork/jobs/deepwork_jobs/steps/learn.md` \ No newline at end of file diff --git a/.claude/commands/deepwork_jobs.refine.md b/.claude/commands/deepwork_jobs.refine.md deleted file mode 100644 index 84479a61..00000000 --- a/.claude/commands/deepwork_jobs.refine.md +++ /dev/null @@ -1,595 +0,0 @@ ---- -description: Modify an existing job definition -hooks: - Stop: - - hooks: - - type: prompt - prompt: | - You must evaluate whether Claude has met all the below quality criteria for the request. - - ## Quality Criteria - - Verify the refinement meets ALL quality criteria before completing: - - 1. **Job Consistency**: Do the changes maintain overall job consistency? - 2. **Valid Dependencies**: Are all step dependencies logically valid (no circular refs)? - 3. **Semantic Versioning**: Was the version bumped appropriately (major/minor/patch)? - 4. **Changelog Updated**: Is the changelog updated with a description of changes? - 5. **User Understanding**: Does the user understand the impact of the changes? - 6. **Breaking Changes**: Were any breaking changes clearly communicated? - 7. **Files Updated**: Are all affected files (job.yml, step files) updated? - 8. **Sync Complete**: Has `deepwork sync` been run to regenerate commands? - - If ANY criterion is not met, continue working to address it. - If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. - - - ## Instructions - - Review the conversation and determine if ALL quality criteria above have been satisfied. - Look for evidence that each criterion has been addressed. - - If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} - - If criteria are NOT met AND the promise tag is missing, respond with: - {"ok": false, "reason": "Continue working. [specific feedback on what's wrong]"} ---- - -# deepwork_jobs.refine - -**Standalone command** in the **deepwork_jobs** job - can be run anytime - -**Summary**: DeepWork job management commands - -## Job Overview - -Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and refine existing ones. - -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, -and generating all necessary files. - -The `refine` command helps you modify existing jobs safely by understanding what you want -to change, validating the impact, and ensuring consistency across your workflow. - - - -## Instructions - -# Refine Existing DeepWork Job - -## Objective - -Help the user modify an existing DeepWork job definition by understanding what they want to change and ensuring the modifications maintain consistency and validity. - -## Task - -Guide the user through refining a job by first understanding their existing job, then what they want to change, and finally implementing those changes safely. - -### Step 1: Select and Load Job - -1. **List available jobs** - - Scan `.deepwork/jobs/` directory for installed jobs - - Display installed jobs with versions and descriptions - - Ask which job to refine - -2. **Load job definition** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Parse and understand the current structure - -3. **Show current structure** - - Display all steps with their names and descriptions - - Show the dependency flow - - Highlight key inputs and outputs - -### Step 2: Understand Desired Changes - -Ask the user what they want to change: - -**Change Options:** -1. Add a new step to the workflow -2. Modify step instructions -3. Change step inputs/outputs -4. Update dependencies between steps -5. Update job metadata (description, version) -6. Remove a step -7. Add or modify stop hooks (quality validation) - -**For each change, ask clarifying questions:** -- Why do they want to make this change? -- How will it improve the workflow? -- Are there dependencies or side effects to consider? - -### Step 3: Make Changes Safely - -Based on the user's selection: - -#### Adding a Step - -1. **Gather step details** (same as define command) - - What does this step accomplish? - - What are the inputs? User parameters or file inputs? - - What outputs does it produce? - - What are the dependencies? - -2. **Determine placement** - - Where should it go in the workflow? - - Before which existing step? - - Or at the end? - -3. **Validate placement** - - Can't depend on later steps if inserted early - - File inputs must come from dependencies - - Check for circular dependencies - -4. **Update files** - - Update `job.yml` with new step - - Create step instructions file in `steps/[step_id].md` - - Prepare changelog entry describing the addition - -#### Modifying Step Instructions - -1. **Select step to modify** - - Show list of steps - - Ask which one to modify - -2. **Understand the change** - - What's not working with current instructions? - - What should be different? - - Show current instructions - -3. **Update instructions** - - Modify `.deepwork/jobs/[job_name]/steps/[step_id].md` - - Keep the same structure (Objective, Task, Process, Output Format, Quality Criteria) - - Prepare changelog entry describing the modification - -#### Changing Inputs/Outputs - -1. **Select step to modify** -2. **Show current inputs and outputs** -3. **Understand the change** - - Adding or removing? - - Why is this needed? - -4. **Validate impact** - - If removing output: check if other steps depend on it (BREAKING CHANGE) - - If adding file input: ensure from_step is in dependencies - - If removing input: ensure it's not critical - -5. **Update job.yml** - - Prepare changelog entry describing the input/output changes - -#### Updating Dependencies - -1. **Select step to modify** -2. **Show current dependency graph** -3. **Understand the change** - - Adding or removing dependency? - - Why? - -4. **Validate** - - Check for circular dependencies - - Ensure all file inputs have matching dependencies - - Ensure dependency chain makes logical sense - -5. **Update job.yml** - - Prepare changelog entry describing the dependency changes - -#### Updating Metadata - -1. **Ask what to change** - - Description? - - Version? - -2. **If version change, explain semantic versioning** - - Major (x.0.0): Breaking changes (removing steps, removing outputs) - - Minor (0.x.0): New features, backwards compatible (adding steps) - - Patch (0.0.x): Bug fixes, improvements - -3. **Update job.yml** - - Prepare changelog entry describing the metadata changes - -#### Removing a Step - -1. **Select step to remove** - -2. **CRITICAL: Validate safety** - - Check if other steps depend on this step - - Check if other steps use outputs from this step - - If dependencies exist: **WARN** and suggest updating dependents first - - This is a BREAKING CHANGE - requires major version bump - -3. **If safe to remove** - - Remove from `job.yml` - - Delete step instructions file - - Suggest version bump - - Prepare changelog entry describing the removal - -#### Adding or Modifying Stop Hooks - -Stop hooks provide quality validation loops that ensure step outputs meet criteria before completing. - -1. **Select step to modify** - - Show list of steps - - Ask which one to add/modify hooks for - -2. **Understand the need** - - What quality criteria should be validated? - - Is the output subjective (use prompt hook) or objective (use script hook)? - - Should validation happen automatically or only on specific conditions? - -3. **Choose hook type** - - **Prompt hooks** (recommended for most cases): - - Best for subjective quality criteria - - AI evaluates the output against criteria - - Example: "Verify the report is comprehensive and well-organized" - ```yaml - stop_hooks: - - prompt: | - Verify the output meets criteria: - 1. Contains all required sections - 2. Analysis is thorough - 3. Recommendations are actionable - ``` - - **Prompt file hooks**: - - For reusable or complex validation criteria - - Stores criteria in a separate markdown file - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - - **Script hooks**: - - For objective, programmatic validation - - Best for tests, linting, format checking - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -4. **Multiple hooks can be combined** - ```yaml - stop_hooks: - - script: hooks/lint.sh # First: objective checks - - prompt: "Verify content quality" # Then: subjective review - ``` - -5. **Update files** - - Add/modify `stop_hooks` array in job.yml - - Create hook files if using prompt_file or script types - - Update step instructions to match quality criteria - - Prepare changelog entry - -6. **Encourage prompt-based hooks** - - They leverage the AI's ability to understand context - - More flexible than rigid script checks - - Can evaluate nuanced quality criteria - -### Step 4: Update Changelog - -After making changes to the job.yml: - -1. **Add a changelog entry** - - Add a new entry to the `changelog` array in the job.yml - - Use the new version number - - List all changes made in this refinement - -2. **Changelog entry format**: - ```yaml - - version: "[new_version]" - changes: "[Description of all changes in this version]" - ``` - -3. **Example changelog entries**: - - "Added step: validate_positioning" - - "Modified step instructions for research_competitors to improve clarity and add quality criteria" - - "Removed step: duplicate_analysis (consolidated into comparative_analysis)" - - "Updated dependencies: positioning_recommendations now depends on validate_positioning" - - "Changed output filename: comparison_matrix.md → comparison_table.md" - - "Added step: validate_positioning; Updated dependencies for positioning_recommendations" - -### Step 5: Validate Changes - -After updating the changelog: - -1. **Review the updated structure** - - Show the complete updated workflow - - Highlight what changed - - Check for consistency - -2. **Validate job definition** - - No circular dependencies - - All file inputs match dependencies - - All step IDs unique - - All outputs defined - -3. **Confirm version update** - - Ensure version was bumped appropriately - - Breaking changes? Major version - - New features? Minor version - - Improvements? Patch version - -### Step 6: Sync and Reload - -1. **Run sync** - ```bash - deepwork sync - ``` - -2. **Reload commands** - - Instruct user to run `/reload` or restart session - -3. **Provide summary** - - Show what changed - - List updated files - - Display the changelog entry - - Explain next steps - -## Safe Modification Patterns - -Guide users toward safe changes: - -### Safe Changes (Always OK) -- Adding steps at the end with new outputs -- Updating step instructions (content only) -- Changing job description -- Adding user inputs to a step -- Adding outputs (not removing) -- Patch version bumps - -### Potentially Breaking Changes (Warn User) -- Removing steps -- Removing outputs -- Removing inputs -- Changing dependencies -- Renaming outputs (other steps may reference them) -- Requires major or minor version bump - -### Always Validate -- Circular dependencies after any dependency change -- File inputs match dependencies after any change -- Step IDs remain unique -- At least one output per step - -## Example Dialog - -``` -Claude: I'll help you refine an existing job. Here are your installed jobs: - -1. competitive_research v1.0.0 - Systematic competitive analysis workflow -2. blog_post v1.0.0 - Blog post creation workflow - -Which job would you like to refine? - -User: 1 - -Claude: Loading competitive_research v1.0.0... - -Current structure: -- Step 1: identify_competitors - Identify 5-7 competitors in target market -- Step 2: research_competitors - Deep research on each competitor -- Step 3: comparative_analysis - Side-by-side comparison matrix -- Step 4: positioning_recommendations - Strategic positioning report - -What would you like to change? -1. Add a new step -2. Modify step instructions -3. Change inputs/outputs -4. Update dependencies -5. Update job metadata -6. Remove a step - -User: 1 - -Claude: Great! Let's add a new step. First, help me understand: - -1. What should this new step accomplish? -2. Where should it fit in the workflow? - - Should it go between existing steps or at the end? - -User: I want to add a step that validates our product positioning before the final recommendations. It should go between step 3 and step 4. - -Claude: Excellent idea. So this would be: -- Step 4: validate_positioning -- Step 5: positioning_recommendations (renumbered) - -For this validation step: -1. What inputs does it need? I assume it needs the comparison_matrix.md from step 3? -2. What should it output? -3. What exactly should this validation check for? - -User: Yes, it needs the comparison matrix. It should output a validation_report.md that identifies gaps in our positioning. - -Claude: Perfect. Let me confirm the details: - -**New Step: validate_positioning** -- Name: "Validate Product Positioning" -- Description: "Identify gaps and opportunities in current positioning" -- Inputs: comparison_matrix.md (from comparative_analysis step) -- Outputs: validation_report.md -- Dependencies: comparative_analysis -- Position: Between step 3 and 4 - -Should the positioning_recommendations step also use the validation_report.md as input? - -User: Yes, definitely - -Claude: Great! So I'll also update the positioning_recommendations step to include validation_report.md as an input and add validate_positioning as a dependency. - -This is a new feature, so I'll bump the version to 1.1.0 (minor version). - -Creating the new step... ✓ - -Updated files: -- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0, updated changelog) -- .deepwork/jobs/competitive_research/steps/validate_positioning.md (created) - -Changelog entry added: -```yaml -- version: "1.1.0" - changes: "Added step: validate_positioning between comparative_analysis and positioning_recommendations; Updated dependencies for positioning_recommendations" -``` - -Now run: -```bash -deepwork sync -``` - -Then reload your session and you'll have: -- /competitive_research.validate_positioning (new!) -- All other commands updated -``` - -## Validation Rules - -Enforce the same rules as job definition: -- Job name: lowercase, underscores -- Version: semantic versioning -- Step IDs: unique within job -- Dependencies: must reference existing step IDs -- File inputs: `from_step` must be in dependencies -- At least one output per step -- No circular dependencies - -## Error Handling - -If issues arise, provide clear guidance: -- **Dependency conflict**: "Step X depends on step Y which you're trying to remove. You must update step X first, or remove both steps." -- **Circular dependency**: "Adding this dependency would create a cycle: A → B → C → A. Please choose a different dependency structure." -- **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies. I'll add Y to the dependencies." -- **Breaking change**: "Removing this output is a breaking change. Other steps depend on it. I recommend against this change unless you update the dependent steps first." - -## Changelog Entry Format - -Instead of creating a separate refinement_summary.md file, add the changes directly to the job.yml changelog section. This creates a permanent version history within the job definition itself. - -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -**Add to the `changelog` array**: - -```yaml -changelog: - - version: "1.0.0" - changes: "Initial job creation" - - version: "[new_version]" - changes: "[Concise description of all changes in this version]" -``` - -**Guidelines for changelog entries**: -- Be concise but descriptive -- Use action verbs (Added, Modified, Removed, Updated, Changed, Fixed) -- Reference specific step names when relevant -- For breaking changes, prefix with "BREAKING:" -- If multiple changes, separate with semicolons or use clear phrasing - -**Examples**: -- "Added step: validate_positioning between comparative_analysis and positioning_recommendations" -- "Modified step instructions for research_competitors to improve clarity and add quality criteria" -- "Removed step: duplicate_analysis (consolidated into comparative_analysis)" -- "Updated dependencies: positioning_recommendations now depends on validate_positioning" -- "Changed output filename: comparison_matrix.md → comparison_table.md" -- "BREAKING: Removed output file shared_data.json from identify_competitors step" -- "Fixed circular dependency between steps A and B" -- "Updated job description to reflect new validation phase" -- "Added validate_positioning step; Updated dependencies for positioning_recommendations" - -## Quality Criteria - -- Changes maintain job consistency -- Dependencies are logically valid -- Version bump follows semantic versioning -- No circular dependencies introduced -- User understands impact of changes -- Breaking changes are clearly communicated - - -## Inputs - -### User Parameters - -Please gather the following information from the user: -- **job_name**: Name of the job to refine - - -## Work Branch Management - -All work for this job should be done on a dedicated work branch: - -1. **Check current branch**: - - If already on a work branch for this job (format: `deepwork/deepwork_jobs-[instance]-[date]`), continue using it - - If on main/master, create a new work branch - -2. **Create work branch** (if needed): - ```bash - git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d) - ``` - Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.) - -## Output Requirements - -Create the following output(s): -- `job.yml` -Ensure all outputs are: -- Well-formatted and complete -- Ready for review or use by subsequent steps - -## Quality Validation Loop - -This step uses an iterative quality validation loop. After completing your work, stop hook(s) will evaluate whether the outputs meet quality criteria. If criteria are not met, you will be prompted to continue refining. - -### Quality Criteria -Verify the refinement meets ALL quality criteria before completing: - -1. **Job Consistency**: Do the changes maintain overall job consistency? -2. **Valid Dependencies**: Are all step dependencies logically valid (no circular refs)? -3. **Semantic Versioning**: Was the version bumped appropriately (major/minor/patch)? -4. **Changelog Updated**: Is the changelog updated with a description of changes? -5. **User Understanding**: Does the user understand the impact of the changes? -6. **Breaking Changes**: Were any breaking changes clearly communicated? -7. **Files Updated**: Are all affected files (job.yml, step files) updated? -8. **Sync Complete**: Has `deepwork sync` been run to regenerate commands? - -If ANY criterion is not met, continue working to address it. -If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. - - -### Completion Promise - -To signal that all quality criteria have been met, include this tag in your final response: - -``` -✓ Quality Criteria Met -``` - -**Important**: Only include this promise tag when you have verified that ALL quality criteria above are satisfied. The validation loop will continue until this promise is detected. - -## Completion - -After completing this step: - -1. **Verify outputs**: Confirm all required files have been created - -2. **Inform the user**: - - The refine command is complete - - Outputs created: job.yml - - This command can be run again anytime to make further changes - -## Command Complete - -This is a standalone command that can be run anytime. The outputs are ready for use. - -Consider: -- Reviewing the outputs -- Running `deepwork sync` if job definitions were changed -- Re-running this command later if further changes are needed - ---- - -## Context Files - -- Job definition: `.deepwork/jobs/deepwork_jobs/job.yml` -- Step instructions: `.deepwork/jobs/deepwork_jobs/steps/refine.md` \ No newline at end of file diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 54301f14..7c6b81c1 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -1,20 +1,23 @@ name: deepwork_jobs -version: "0.1.0" +version: "0.2.0" summary: "DeepWork job management commands" description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step - workflows and refine existing ones. + 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, and generating all necessary files. - The `refine` command helps you modify existing jobs safely by understanding what you want - to change, validating the impact, and ensuring consistency across your workflow. + The `learn` command reflects on conversations where DeepWork jobs were run, identifies + confusion or inefficiencies, and improves job instructions. It also captures bespoke + learnings specific to the current run into AGENTS.md files in the working folder. changelog: - version: "0.1.0" changes: "Initial version" + - version: "0.2.0" + changes: "Replaced refine command with learn command for conversation-driven improvement" steps: - id: define @@ -74,29 +77,29 @@ steps: If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. - - id: refine - name: "Refine Existing Job" - description: "Modify an existing job definition" - instructions_file: steps/refine.md + - id: learn + name: "Learn from Job Execution" + description: "Reflect on conversation to improve job instructions and capture learnings" + instructions_file: steps/learn.md inputs: - name: job_name - description: "Name of the job to refine" + description: "Name of the job that was run (optional - will auto-detect from conversation)" outputs: - - job.yml + - learning_summary.md dependencies: [] hooks: after_agent: - prompt: | - Verify the refinement meets ALL quality criteria before completing: + Verify the learning process meets ALL quality criteria before completing: - 1. **Job Consistency**: Do the changes maintain overall job consistency? - 2. **Valid Dependencies**: Are all step dependencies logically valid (no circular refs)? - 3. **Semantic Versioning**: Was the version bumped appropriately (major/minor/patch)? - 4. **Changelog Updated**: Is the changelog updated with a description of changes? - 5. **User Understanding**: Does the user understand the impact of the changes? - 6. **Breaking Changes**: Were any breaking changes clearly communicated? - 7. **Files Updated**: Are all affected files (job.yml, step files) updated? - 8. **Sync Complete**: Has `deepwork sync` been run to regenerate commands? + 1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? + 2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? + 3. **Instructions Improved**: Were job instructions updated to address identified issues? + 4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? + 5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? + 6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? + 7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? + 8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md new file mode 100644 index 00000000..b00f6610 --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -0,0 +1,314 @@ +# Learn from Job Execution + +## Objective + +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. + +## Task + +Analyze the conversation history to extract learnings and improvements, then apply them appropriately: +- **Generalizable learnings** → Update job instruction files +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder + +### Step 1: Analyze Conversation for Job Executions + +1. **Scan the conversation** for DeepWork slash commands that were run + - Look for patterns like `/job_name.step_id` + - Identify which jobs and steps were executed + - Note the order of execution + +2. **Identify the working folder** + - Find where outputs were created during job execution + - This is typically specified in the job's working directory + - Common patterns: project root, `./output/`, or job-specific directories + +3. **If no job was specified**, ask the user: + - "Which DeepWork job would you like me to learn from?" + - List available jobs from `.deepwork/jobs/` + +### Step 2: Identify Points of Confusion and Inefficiency + +Review the conversation for: + +1. **Confusion signals** + - Questions the agent asked that shouldn't have been necessary + - Misunderstandings about what a step required + - Incorrect outputs that needed correction + - Ambiguous instructions that led to wrong interpretations + +2. **Inefficiency signals** + - Extra steps or iterations that were needed + - Information that had to be repeated + - Context that was missing from instructions + - Dependencies that weren't clear + +3. **Error patterns** + - Failed validations and why they failed + - Quality criteria that were misunderstood + - Edge cases that weren't handled + +4. **Success patterns** + - What worked particularly well + - Efficient approaches worth preserving + - Good examples that could be added to instructions + +### Step 3: Classify Learnings + +For each learning identified, determine if it is: + +**Generalizable** (should improve instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions in instructions +- Adds helpful examples or context +- Examples: + - "Step instructions should mention that X format is required" + - "Quality criteria should include checking for Y" + - "Add example of correct output format" + +**Bespoke** (should go in AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions or structure +- References specific files or paths +- Would not apply to other uses of this job +- Examples: + - "In this codebase, API endpoints are in `src/api/`" + - "This project uses camelCase for function names" + - "The main config file is at `config/settings.yml`" + +### Step 4: Update Job Instructions (Generalizable Learnings) + +For each generalizable learning: + +1. **Locate the instruction file** + - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` + +2. **Make targeted improvements** + - Add missing context or clarification + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria if needed + +3. **Preserve instruction structure** + - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) + - Add to appropriate sections rather than restructuring + - Maintain consistency with other steps + +4. **Track changes for changelog** + - Note what was changed and why + - Prepare changelog entry for job.yml + +### Step 5: Create/Update AGENTS.md (Bespoke Learnings) + +The AGENTS.md file captures project-specific knowledge that helps future agent runs. + +1. **Determine the correct location** + - Place AGENTS.md in the working folder where job outputs live + - This ensures the knowledge is available when working in that context + - If uncertain, place at the project root + +2. **Use file references where possible** + - Instead of duplicating information, reference source files + - This keeps AGENTS.md in sync as the codebase evolves + - Pattern: "See `path/to/file.ext` for [description]" + +3. **AGENTS.md structure**: + +```markdown +# Project Context for [Job Name] + +## Codebase Structure + + +- Project structure: See `README.md` for overview +- API documentation: See `docs/api.md` +- Configuration: See `config/README.md` + +## Conventions + +### Naming Conventions +- [Convention]: See example in `path/to/example.ext:LINE` + +### File Organization +- [Pattern]: Reference `path/to/pattern/` + +## Job-Specific Context + +### [Job Name] + +#### [Step Name] +- [Learning]: Reference `relevant/file.ext` +- [Context]: [Brief explanation with file reference] + +## Known Issues and Workarounds + +- [Issue]: [Workaround with file reference if applicable] + +## Last Updated +- Date: [YYYY-MM-DD] +- From conversation about: [Brief description] +``` + +4. **Writing entries** + - Be concise but specific + - Always prefer file references over inline content + - Use line numbers when referencing specific code: `file.ext:42` + - Group related learnings together + +### Step 6: Update Job Version and Changelog + +If instruction files were modified: + +1. **Bump version in job.yml** + - Patch version (0.0.x) for instruction improvements + - Minor version (0.x.0) if quality criteria changed + +2. **Add changelog entry** + ```yaml + - version: "[new_version]" + changes: "Improved [step] instructions based on execution learnings: [brief description]" + ``` + +### Step 7: Sync and Summarize + +1. **Run deepwork sync** (if instructions were modified) + ```bash + deepwork sync + ``` + +2. **Create learning_summary.md** in the working folder: + ```markdown + # Learning Summary + + ## Job Analyzed + - Job: [job_name] + - Steps executed: [list of steps] + + ## Generalizable Improvements Made + - [Step]: [What was improved] + + ## Bespoke Learnings Captured + - Location: [path to AGENTS.md] + - Entries added: [list of entries] + + ## Files Modified + - [List of files changed] + + ## Recommendations + - [Any additional suggestions] + ``` + +3. **Instruct user to reload** if commands were regenerated + +## File Reference Patterns + +When adding entries to AGENTS.md, prefer these patterns: + +**Good (references)**: +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` +``` + +**Avoid (duplicating)**: +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +- Error handling should use try/catch with custom error classes +- Configuration requires these fields: name, version, ... +``` + +## Quality Criteria + +- Conversation has been analyzed for job executions +- Points of confusion and inefficiency are identified +- Learnings are correctly classified (generalizable vs bespoke) +- Job instructions updated for generalizable improvements +- AGENTS.md created/updated with bespoke learnings +- File references used instead of duplicating content +- AGENTS.md is in the correct working folder +- learning_summary.md documents all changes +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.learn + +Claude: I'll analyze this conversation for learnings from DeepWork job executions. + +**Conversation Analysis** + +I found the following job executions: +1. `/competitive_research.identify_competitors` - Completed +2. `/competitive_research.research_competitors` - Completed with 2 iterations +3. `/competitive_research.comparative_analysis` - Completed + +**Identified Issues** + +1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. + +2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. + +**Classification** + +- Generalizable: Add pricing to research requirements in instructions +- Bespoke: This project focuses on B2B SaaS in the HR tech space + +**Actions Taken** + +1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: + - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements + - Added note about carrying forward industry context from previous step + +2. Created `./competitive_research_output/AGENTS.md`: + ```markdown + # Project Context for Competitive Research + + ## Job-Specific Context + + ### competitive_research + + #### Industry Focus + - Domain: B2B SaaS, HR Technology sector + - See `identify_competitors_output.md` for market definition + + #### Competitors Identified + - Reference: `competitor_list.md` for full details + + ## Last Updated + - Date: 2024-01-15 + - From conversation about: Initial competitive analysis run + ``` + +3. Updated job.yml version to 1.0.1 with changelog entry + +4. Ran `deepwork sync` + +**Summary** + +Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +``` + +## Handling Edge Cases + +**No job executions found**: +- Ask user which job they'd like to analyze +- Or offer to review available jobs + +**Multiple jobs executed**: +- Analyze each job separately +- Create separate AGENTS.md entries or files as appropriate + +**AGENTS.md already exists**: +- Read existing content +- Append new learnings to appropriate sections +- Update "Last Updated" section + +**No issues found**: +- Document what worked well +- Consider if any successful patterns should be added to instructions as examples + +**Sensitive information**: +- Never include secrets, credentials, or PII in AGENTS.md +- Reference config files instead of including values diff --git a/.deepwork/jobs/deepwork_jobs/steps/refine.md b/.deepwork/jobs/deepwork_jobs/steps/refine.md deleted file mode 100644 index 389ce009..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/refine.md +++ /dev/null @@ -1,447 +0,0 @@ -# Refine Existing DeepWork Job - -## Objective - -Help the user modify an existing DeepWork job definition by understanding what they want to change and ensuring the modifications maintain consistency and validity. - -## Task - -Guide the user through refining a job by first understanding their existing job, then what they want to change, and finally implementing those changes safely. - -### Step 1: Select and Load Job - -1. **List available jobs** - - Scan `.deepwork/jobs/` directory for installed jobs - - Display installed jobs with versions and descriptions - - Ask which job to refine - -2. **Load job definition** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Parse and understand the current structure - -3. **Show current structure** - - Display all steps with their names and descriptions - - Show the dependency flow - - Highlight key inputs and outputs - -### Step 2: Understand Desired Changes - -Ask the user what they want to change: - -**Change Options:** -1. Add a new step to the workflow -2. Modify step instructions -3. Change step inputs/outputs -4. Update dependencies between steps -5. Update job metadata (description, version) -6. Remove a step -7. Add or modify stop hooks (quality validation) - -**For each change, ask clarifying questions:** -- Why do they want to make this change? -- How will it improve the workflow? -- Are there dependencies or side effects to consider? - -### Step 3: Make Changes Safely - -Based on the user's selection: - -#### Adding a Step - -1. **Gather step details** (same as define command) - - What does this step accomplish? - - What are the inputs? User parameters or file inputs? - - What outputs does it produce? - - What are the dependencies? - -2. **Determine placement** - - Where should it go in the workflow? - - Before which existing step? - - Or at the end? - -3. **Validate placement** - - Can't depend on later steps if inserted early - - File inputs must come from dependencies - - Check for circular dependencies - -4. **Update files** - - Update `job.yml` with new step - - Create step instructions file in `steps/[step_id].md` - - Prepare changelog entry describing the addition - -#### Modifying Step Instructions - -1. **Select step to modify** - - Show list of steps - - Ask which one to modify - -2. **Understand the change** - - What's not working with current instructions? - - What should be different? - - Show current instructions - -3. **Update instructions** - - Modify `.deepwork/jobs/[job_name]/steps/[step_id].md` - - Keep the same structure (Objective, Task, Process, Output Format, Quality Criteria) - - Prepare changelog entry describing the modification - -#### Changing Inputs/Outputs - -1. **Select step to modify** -2. **Show current inputs and outputs** -3. **Understand the change** - - Adding or removing? - - Why is this needed? - -4. **Validate impact** - - If removing output: check if other steps depend on it (BREAKING CHANGE) - - If adding file input: ensure from_step is in dependencies - - If removing input: ensure it's not critical - -5. **Update job.yml** - - Prepare changelog entry describing the input/output changes - -#### Updating Dependencies - -1. **Select step to modify** -2. **Show current dependency graph** -3. **Understand the change** - - Adding or removing dependency? - - Why? - -4. **Validate** - - Check for circular dependencies - - Ensure all file inputs have matching dependencies - - Ensure dependency chain makes logical sense - -5. **Update job.yml** - - Prepare changelog entry describing the dependency changes - -#### Updating Metadata - -1. **Ask what to change** - - Description? - - Version? - -2. **If version change, explain semantic versioning** - - Major (x.0.0): Breaking changes (removing steps, removing outputs) - - Minor (0.x.0): New features, backwards compatible (adding steps) - - Patch (0.0.x): Bug fixes, improvements - -3. **Update job.yml** - - Prepare changelog entry describing the metadata changes - -#### Removing a Step - -1. **Select step to remove** - -2. **CRITICAL: Validate safety** - - Check if other steps depend on this step - - Check if other steps use outputs from this step - - If dependencies exist: **WARN** and suggest updating dependents first - - This is a BREAKING CHANGE - requires major version bump - -3. **If safe to remove** - - Remove from `job.yml` - - Delete step instructions file - - Suggest version bump - - Prepare changelog entry describing the removal - -#### Adding or Modifying Stop Hooks - -Stop hooks provide quality validation loops that ensure step outputs meet criteria before completing. - -1. **Select step to modify** - - Show list of steps - - Ask which one to add/modify hooks for - -2. **Understand the need** - - What quality criteria should be validated? - - Is the output subjective (use prompt hook) or objective (use script hook)? - - Should validation happen automatically or only on specific conditions? - -3. **Choose hook type** - - **Prompt hooks** (recommended for most cases): - - Best for subjective quality criteria - - AI evaluates the output against criteria - - Example: "Verify the report is comprehensive and well-organized" - ```yaml - stop_hooks: - - prompt: | - Verify the output meets criteria: - 1. Contains all required sections - 2. Analysis is thorough - 3. Recommendations are actionable - ``` - - **Prompt file hooks**: - - For reusable or complex validation criteria - - Stores criteria in a separate markdown file - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - - **Script hooks**: - - For objective, programmatic validation - - Best for tests, linting, format checking - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -4. **Multiple hooks can be combined** - ```yaml - stop_hooks: - - script: hooks/lint.sh # First: objective checks - - prompt: "Verify content quality" # Then: subjective review - ``` - -5. **Update files** - - Add/modify `stop_hooks` array in job.yml - - Create hook files if using prompt_file or script types - - Update step instructions to match quality criteria - - Prepare changelog entry - -6. **Encourage prompt-based hooks** - - They leverage the AI's ability to understand context - - More flexible than rigid script checks - - Can evaluate nuanced quality criteria - -### Step 4: Update Changelog - -After making changes to the job.yml: - -1. **Add a changelog entry** - - Add a new entry to the `changelog` array in the job.yml - - Use the new version number - - List all changes made in this refinement - -2. **Changelog entry format**: - ```yaml - - version: "[new_version]" - changes: "[Description of all changes in this version]" - ``` - -3. **Example changelog entries**: - - "Added step: validate_positioning" - - "Modified step instructions for research_competitors to improve clarity and add quality criteria" - - "Removed step: duplicate_analysis (consolidated into comparative_analysis)" - - "Updated dependencies: positioning_recommendations now depends on validate_positioning" - - "Changed output filename: comparison_matrix.md → comparison_table.md" - - "Added step: validate_positioning; Updated dependencies for positioning_recommendations" - -### Step 5: Validate Changes - -After updating the changelog: - -1. **Review the updated structure** - - Show the complete updated workflow - - Highlight what changed - - Check for consistency - -2. **Validate job definition** - - No circular dependencies - - All file inputs match dependencies - - All step IDs unique - - All outputs defined - -3. **Confirm version update** - - Ensure version was bumped appropriately - - Breaking changes? Major version - - New features? Minor version - - Improvements? Patch version - -### Step 6: Sync and Reload - -1. **Run sync** - ```bash - deepwork sync - ``` - -2. **Reload commands** - - Instruct user to run `/reload` or restart session - -3. **Provide summary** - - Show what changed - - List updated files - - Display the changelog entry - - Explain next steps - -## Safe Modification Patterns - -Guide users toward safe changes: - -### Safe Changes (Always OK) -- Adding steps at the end with new outputs -- Updating step instructions (content only) -- Changing job description -- Adding user inputs to a step -- Adding outputs (not removing) -- Patch version bumps - -### Potentially Breaking Changes (Warn User) -- Removing steps -- Removing outputs -- Removing inputs -- Changing dependencies -- Renaming outputs (other steps may reference them) -- Requires major or minor version bump - -### Always Validate -- Circular dependencies after any dependency change -- File inputs match dependencies after any change -- Step IDs remain unique -- At least one output per step - -## Example Dialog - -``` -Claude: I'll help you refine an existing job. Here are your installed jobs: - -1. competitive_research v1.0.0 - Systematic competitive analysis workflow -2. blog_post v1.0.0 - Blog post creation workflow - -Which job would you like to refine? - -User: 1 - -Claude: Loading competitive_research v1.0.0... - -Current structure: -- Step 1: identify_competitors - Identify 5-7 competitors in target market -- Step 2: research_competitors - Deep research on each competitor -- Step 3: comparative_analysis - Side-by-side comparison matrix -- Step 4: positioning_recommendations - Strategic positioning report - -What would you like to change? -1. Add a new step -2. Modify step instructions -3. Change inputs/outputs -4. Update dependencies -5. Update job metadata -6. Remove a step - -User: 1 - -Claude: Great! Let's add a new step. First, help me understand: - -1. What should this new step accomplish? -2. Where should it fit in the workflow? - - Should it go between existing steps or at the end? - -User: I want to add a step that validates our product positioning before the final recommendations. It should go between step 3 and step 4. - -Claude: Excellent idea. So this would be: -- Step 4: validate_positioning -- Step 5: positioning_recommendations (renumbered) - -For this validation step: -1. What inputs does it need? I assume it needs the comparison_matrix.md from step 3? -2. What should it output? -3. What exactly should this validation check for? - -User: Yes, it needs the comparison matrix. It should output a validation_report.md that identifies gaps in our positioning. - -Claude: Perfect. Let me confirm the details: - -**New Step: validate_positioning** -- Name: "Validate Product Positioning" -- Description: "Identify gaps and opportunities in current positioning" -- Inputs: comparison_matrix.md (from comparative_analysis step) -- Outputs: validation_report.md -- Dependencies: comparative_analysis -- Position: Between step 3 and 4 - -Should the positioning_recommendations step also use the validation_report.md as input? - -User: Yes, definitely - -Claude: Great! So I'll also update the positioning_recommendations step to include validation_report.md as an input and add validate_positioning as a dependency. - -This is a new feature, so I'll bump the version to 1.1.0 (minor version). - -Creating the new step... ✓ - -Updated files: -- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0, updated changelog) -- .deepwork/jobs/competitive_research/steps/validate_positioning.md (created) - -Changelog entry added: -```yaml -- version: "1.1.0" - changes: "Added step: validate_positioning between comparative_analysis and positioning_recommendations; Updated dependencies for positioning_recommendations" -``` - -Now run: -```bash -deepwork sync -``` - -Then reload your session and you'll have: -- /competitive_research.validate_positioning (new!) -- All other commands updated -``` - -## Validation Rules - -Enforce the same rules as job definition: -- Job name: lowercase, underscores -- Version: semantic versioning -- Step IDs: unique within job -- Dependencies: must reference existing step IDs -- File inputs: `from_step` must be in dependencies -- At least one output per step -- No circular dependencies - -## Error Handling - -If issues arise, provide clear guidance: -- **Dependency conflict**: "Step X depends on step Y which you're trying to remove. You must update step X first, or remove both steps." -- **Circular dependency**: "Adding this dependency would create a cycle: A → B → C → A. Please choose a different dependency structure." -- **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies. I'll add Y to the dependencies." -- **Breaking change**: "Removing this output is a breaking change. Other steps depend on it. I recommend against this change unless you update the dependent steps first." - -## Changelog Entry Format - -Instead of creating a separate refinement_summary.md file, add the changes directly to the job.yml changelog section. This creates a permanent version history within the job definition itself. - -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -**Add to the `changelog` array**: - -```yaml -changelog: - - version: "1.0.0" - changes: "Initial job creation" - - version: "[new_version]" - changes: "[Concise description of all changes in this version]" -``` - -**Guidelines for changelog entries**: -- Be concise but descriptive -- Use action verbs (Added, Modified, Removed, Updated, Changed, Fixed) -- Reference specific step names when relevant -- For breaking changes, prefix with "BREAKING:" -- If multiple changes, separate with semicolons or use clear phrasing - -**Examples**: -- "Added step: validate_positioning between comparative_analysis and positioning_recommendations" -- "Modified step instructions for research_competitors to improve clarity and add quality criteria" -- "Removed step: duplicate_analysis (consolidated into comparative_analysis)" -- "Updated dependencies: positioning_recommendations now depends on validate_positioning" -- "Changed output filename: comparison_matrix.md → comparison_table.md" -- "BREAKING: Removed output file shared_data.json from identify_competitors step" -- "Fixed circular dependency between steps A and B" -- "Updated job description to reflect new validation phase" -- "Added validate_positioning step; Updated dependencies for positioning_recommendations" - -## Quality Criteria - -- Changes maintain job consistency -- Dependencies are logically valid -- Version bump follows semantic versioning -- No circular dependencies introduced -- User understands impact of changes -- Breaking changes are clearly communicated diff --git a/.gemini/commands/deepwork_jobs/define.toml b/.gemini/commands/deepwork_jobs/define.toml index 8d16386b..563b8c6e 100644 --- a/.gemini/commands/deepwork_jobs/define.toml +++ b/.gemini/commands/deepwork_jobs/define.toml @@ -16,14 +16,15 @@ prompt = """ ## Job Overview Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and refine existing ones. +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, and generating all necessary files. -The `refine` command helps you modify existing jobs safely by understanding what you want -to change, validating the impact, and ensuring consistency across your workflow. +The `learn` command reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.gemini/commands/deepwork_jobs/implement.toml b/.gemini/commands/deepwork_jobs/implement.toml index d5f7dc19..6eae959e 100644 --- a/.gemini/commands/deepwork_jobs/implement.toml +++ b/.gemini/commands/deepwork_jobs/implement.toml @@ -16,14 +16,15 @@ prompt = """ ## Job Overview Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and refine existing ones. +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, and generating all necessary files. -The `refine` command helps you modify existing jobs safely by understanding what you want -to change, validating the impact, and ensuring consistency across your workflow. +The `learn` command reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. ## Prerequisites @@ -514,13 +515,13 @@ After completing this step: 2. **Inform the user**: - Step 2 of 3 is complete - Outputs created: implementation_summary.md - - Ready to proceed to next step: `/deepwork_jobs:refine` + - Ready to proceed to next step: `/deepwork_jobs:learn` ## Next Step To continue the workflow, run: ``` -/deepwork_jobs:refine +/deepwork_jobs:learn ``` --- diff --git a/.gemini/commands/deepwork_jobs/learn.toml b/.gemini/commands/deepwork_jobs/learn.toml new file mode 100644 index 00000000..4f3c412e --- /dev/null +++ b/.gemini/commands/deepwork_jobs/learn.toml @@ -0,0 +1,406 @@ +# deepwork_jobs:learn +# +# Reflect on conversation to improve job instructions and capture learnings +# +# Generated by DeepWork - do not edit manually + +description = "Reflect on conversation to improve job instructions and capture learnings" + +prompt = """ +# deepwork_jobs:learn + +**Standalone command** in the **deepwork_jobs** job - can be run anytime + +**Summary**: DeepWork job management commands + +## Job Overview + +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, +and generating all necessary files. + +The `learn` command reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. + + + +## Instructions + +# Learn from Job Execution + +## Objective + +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. + +## Task + +Analyze the conversation history to extract learnings and improvements, then apply them appropriately: +- **Generalizable learnings** → Update job instruction files +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder + +### Step 1: Analyze Conversation for Job Executions + +1. **Scan the conversation** for DeepWork slash commands that were run + - Look for patterns like `/job_name.step_id` + - Identify which jobs and steps were executed + - Note the order of execution + +2. **Identify the working folder** + - Find where outputs were created during job execution + - This is typically specified in the job's working directory + - Common patterns: project root, `./output/`, or job-specific directories + +3. **If no job was specified**, ask the user: + - "Which DeepWork job would you like me to learn from?" + - List available jobs from `.deepwork/jobs/` + +### Step 2: Identify Points of Confusion and Inefficiency + +Review the conversation for: + +1. **Confusion signals** + - Questions the agent asked that shouldn't have been necessary + - Misunderstandings about what a step required + - Incorrect outputs that needed correction + - Ambiguous instructions that led to wrong interpretations + +2. **Inefficiency signals** + - Extra steps or iterations that were needed + - Information that had to be repeated + - Context that was missing from instructions + - Dependencies that weren't clear + +3. **Error patterns** + - Failed validations and why they failed + - Quality criteria that were misunderstood + - Edge cases that weren't handled + +4. **Success patterns** + - What worked particularly well + - Efficient approaches worth preserving + - Good examples that could be added to instructions + +### Step 3: Classify Learnings + +For each learning identified, determine if it is: + +**Generalizable** (should improve instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions in instructions +- Adds helpful examples or context +- Examples: + - "Step instructions should mention that X format is required" + - "Quality criteria should include checking for Y" + - "Add example of correct output format" + +**Bespoke** (should go in AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions or structure +- References specific files or paths +- Would not apply to other uses of this job +- Examples: + - "In this codebase, API endpoints are in `src/api/`" + - "This project uses camelCase for function names" + - "The main config file is at `config/settings.yml`" + +### Step 4: Update Job Instructions (Generalizable Learnings) + +For each generalizable learning: + +1. **Locate the instruction file** + - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` + +2. **Make targeted improvements** + - Add missing context or clarification + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria if needed + +3. **Preserve instruction structure** + - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) + - Add to appropriate sections rather than restructuring + - Maintain consistency with other steps + +4. **Track changes for changelog** + - Note what was changed and why + - Prepare changelog entry for job.yml + +### Step 5: Create/Update AGENTS.md (Bespoke Learnings) + +The AGENTS.md file captures project-specific knowledge that helps future agent runs. + +1. **Determine the correct location** + - Place AGENTS.md in the working folder where job outputs live + - This ensures the knowledge is available when working in that context + - If uncertain, place at the project root + +2. **Use file references where possible** + - Instead of duplicating information, reference source files + - This keeps AGENTS.md in sync as the codebase evolves + - Pattern: "See `path/to/file.ext` for [description]" + +3. **AGENTS.md structure**: + +```markdown +# Project Context for [Job Name] + +## Codebase Structure + + +- Project structure: See `README.md` for overview +- API documentation: See `docs/api.md` +- Configuration: See `config/README.md` + +## Conventions + +### Naming Conventions +- [Convention]: See example in `path/to/example.ext:LINE` + +### File Organization +- [Pattern]: Reference `path/to/pattern/` + +## Job-Specific Context + +### [Job Name] + +#### [Step Name] +- [Learning]: Reference `relevant/file.ext` +- [Context]: [Brief explanation with file reference] + +## Known Issues and Workarounds + +- [Issue]: [Workaround with file reference if applicable] + +## Last Updated +- Date: [YYYY-MM-DD] +- From conversation about: [Brief description] +``` + +4. **Writing entries** + - Be concise but specific + - Always prefer file references over inline content + - Use line numbers when referencing specific code: `file.ext:42` + - Group related learnings together + +### Step 6: Update Job Version and Changelog + +If instruction files were modified: + +1. **Bump version in job.yml** + - Patch version (0.0.x) for instruction improvements + - Minor version (0.x.0) if quality criteria changed + +2. **Add changelog entry** + ```yaml + - version: "[new_version]" + changes: "Improved [step] instructions based on execution learnings: [brief description]" + ``` + +### Step 7: Sync and Summarize + +1. **Run deepwork sync** (if instructions were modified) + ```bash + deepwork sync + ``` + +2. **Create learning_summary.md** in the working folder: + ```markdown + # Learning Summary + + ## Job Analyzed + - Job: [job_name] + - Steps executed: [list of steps] + + ## Generalizable Improvements Made + - [Step]: [What was improved] + + ## Bespoke Learnings Captured + - Location: [path to AGENTS.md] + - Entries added: [list of entries] + + ## Files Modified + - [List of files changed] + + ## Recommendations + - [Any additional suggestions] + ``` + +3. **Instruct user to reload** if commands were regenerated + +## File Reference Patterns + +When adding entries to AGENTS.md, prefer these patterns: + +**Good (references)**: +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` +``` + +**Avoid (duplicating)**: +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +- Error handling should use try/catch with custom error classes +- Configuration requires these fields: name, version, ... +``` + +## Quality Criteria + +- Conversation has been analyzed for job executions +- Points of confusion and inefficiency are identified +- Learnings are correctly classified (generalizable vs bespoke) +- Job instructions updated for generalizable improvements +- AGENTS.md created/updated with bespoke learnings +- File references used instead of duplicating content +- AGENTS.md is in the correct working folder +- learning_summary.md documents all changes +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.learn + +Claude: I'll analyze this conversation for learnings from DeepWork job executions. + +**Conversation Analysis** + +I found the following job executions: +1. `/competitive_research.identify_competitors` - Completed +2. `/competitive_research.research_competitors` - Completed with 2 iterations +3. `/competitive_research.comparative_analysis` - Completed + +**Identified Issues** + +1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. + +2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. + +**Classification** + +- Generalizable: Add pricing to research requirements in instructions +- Bespoke: This project focuses on B2B SaaS in the HR tech space + +**Actions Taken** + +1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: + - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements + - Added note about carrying forward industry context from previous step + +2. Created `./competitive_research_output/AGENTS.md`: + ```markdown + # Project Context for Competitive Research + + ## Job-Specific Context + + ### competitive_research + + #### Industry Focus + - Domain: B2B SaaS, HR Technology sector + - See `identify_competitors_output.md` for market definition + + #### Competitors Identified + - Reference: `competitor_list.md` for full details + + ## Last Updated + - Date: 2024-01-15 + - From conversation about: Initial competitive analysis run + ``` + +3. Updated job.yml version to 1.0.1 with changelog entry + +4. Ran `deepwork sync` + +**Summary** + +Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +``` + +## Handling Edge Cases + +**No job executions found**: +- Ask user which job they'd like to analyze +- Or offer to review available jobs + +**Multiple jobs executed**: +- Analyze each job separately +- Create separate AGENTS.md entries or files as appropriate + +**AGENTS.md already exists**: +- Read existing content +- Append new learnings to appropriate sections +- Update "Last Updated" section + +**No issues found**: +- Document what worked well +- Consider if any successful patterns should be added to instructions as examples + +**Sensitive information**: +- Never include secrets, credentials, or PII in AGENTS.md +- Reference config files instead of including values + + +## Inputs + +### User Parameters + +Please gather the following information from the user: +- **job_name**: Name of the job that was run (optional - will auto-detect from conversation) + + +## Work Branch Management + +All work for this job should be done on a dedicated work branch: + +1. **Check current branch**: + - If already on a work branch for this job (format: `deepwork/deepwork_jobs-[instance]-[date]`), continue using it + - If on main/master, create a new work branch + +2. **Create work branch** (if needed): + ```bash + git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d) + ``` + Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.) + +## Output Requirements + +Create the following output(s): +- `learning_summary.md` + +Ensure all outputs are: +- Well-formatted and complete +- Ready for review or use by subsequent steps + +## Completion + +After completing this step: + +1. **Verify outputs**: Confirm all required files have been created + +2. **Inform the user**: + - The learn command is complete + - Outputs created: learning_summary.md + - This command can be run again anytime to make further changes + +## Command Complete + +This is a standalone command that can be run anytime. The outputs are ready for use. + +Consider: +- Reviewing the outputs +- Running `deepwork sync` if job definitions were changed +- Re-running this command later if further changes are needed + +--- + +## Context Files + +- Job definition: `.deepwork/jobs/deepwork_jobs/job.yml` +- Step instructions: `.deepwork/jobs/deepwork_jobs/steps/learn.md` +""" \ No newline at end of file diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 54301f14..7c6b81c1 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1,20 +1,23 @@ name: deepwork_jobs -version: "0.1.0" +version: "0.2.0" summary: "DeepWork job management commands" description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step - workflows and refine existing ones. + 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, and generating all necessary files. - The `refine` command helps you modify existing jobs safely by understanding what you want - to change, validating the impact, and ensuring consistency across your workflow. + The `learn` command reflects on conversations where DeepWork jobs were run, identifies + confusion or inefficiencies, and improves job instructions. It also captures bespoke + learnings specific to the current run into AGENTS.md files in the working folder. changelog: - version: "0.1.0" changes: "Initial version" + - version: "0.2.0" + changes: "Replaced refine command with learn command for conversation-driven improvement" steps: - id: define @@ -74,29 +77,29 @@ steps: If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. - - id: refine - name: "Refine Existing Job" - description: "Modify an existing job definition" - instructions_file: steps/refine.md + - id: learn + name: "Learn from Job Execution" + description: "Reflect on conversation to improve job instructions and capture learnings" + instructions_file: steps/learn.md inputs: - name: job_name - description: "Name of the job to refine" + description: "Name of the job that was run (optional - will auto-detect from conversation)" outputs: - - job.yml + - learning_summary.md dependencies: [] hooks: after_agent: - prompt: | - Verify the refinement meets ALL quality criteria before completing: + Verify the learning process meets ALL quality criteria before completing: - 1. **Job Consistency**: Do the changes maintain overall job consistency? - 2. **Valid Dependencies**: Are all step dependencies logically valid (no circular refs)? - 3. **Semantic Versioning**: Was the version bumped appropriately (major/minor/patch)? - 4. **Changelog Updated**: Is the changelog updated with a description of changes? - 5. **User Understanding**: Does the user understand the impact of the changes? - 6. **Breaking Changes**: Were any breaking changes clearly communicated? - 7. **Files Updated**: Are all affected files (job.yml, step files) updated? - 8. **Sync Complete**: Has `deepwork sync` been run to regenerate commands? + 1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? + 2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? + 3. **Instructions Improved**: Were job instructions updated to address identified issues? + 4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? + 5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? + 6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? + 7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? + 8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md new file mode 100644 index 00000000..b00f6610 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -0,0 +1,314 @@ +# Learn from Job Execution + +## Objective + +Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. + +## Task + +Analyze the conversation history to extract learnings and improvements, then apply them appropriately: +- **Generalizable learnings** → Update job instruction files +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder + +### Step 1: Analyze Conversation for Job Executions + +1. **Scan the conversation** for DeepWork slash commands that were run + - Look for patterns like `/job_name.step_id` + - Identify which jobs and steps were executed + - Note the order of execution + +2. **Identify the working folder** + - Find where outputs were created during job execution + - This is typically specified in the job's working directory + - Common patterns: project root, `./output/`, or job-specific directories + +3. **If no job was specified**, ask the user: + - "Which DeepWork job would you like me to learn from?" + - List available jobs from `.deepwork/jobs/` + +### Step 2: Identify Points of Confusion and Inefficiency + +Review the conversation for: + +1. **Confusion signals** + - Questions the agent asked that shouldn't have been necessary + - Misunderstandings about what a step required + - Incorrect outputs that needed correction + - Ambiguous instructions that led to wrong interpretations + +2. **Inefficiency signals** + - Extra steps or iterations that were needed + - Information that had to be repeated + - Context that was missing from instructions + - Dependencies that weren't clear + +3. **Error patterns** + - Failed validations and why they failed + - Quality criteria that were misunderstood + - Edge cases that weren't handled + +4. **Success patterns** + - What worked particularly well + - Efficient approaches worth preserving + - Good examples that could be added to instructions + +### Step 3: Classify Learnings + +For each learning identified, determine if it is: + +**Generalizable** (should improve instructions): +- Would help ANY future run of this job +- Addresses unclear or missing guidance +- Fixes incorrect assumptions in instructions +- Adds helpful examples or context +- Examples: + - "Step instructions should mention that X format is required" + - "Quality criteria should include checking for Y" + - "Add example of correct output format" + +**Bespoke** (should go in AGENTS.md): +- Specific to THIS project/codebase/run +- Depends on local conventions or structure +- References specific files or paths +- Would not apply to other uses of this job +- Examples: + - "In this codebase, API endpoints are in `src/api/`" + - "This project uses camelCase for function names" + - "The main config file is at `config/settings.yml`" + +### Step 4: Update Job Instructions (Generalizable Learnings) + +For each generalizable learning: + +1. **Locate the instruction file** + - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` + +2. **Make targeted improvements** + - Add missing context or clarification + - Include helpful examples + - Clarify ambiguous instructions + - Update quality criteria if needed + +3. **Preserve instruction structure** + - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) + - Add to appropriate sections rather than restructuring + - Maintain consistency with other steps + +4. **Track changes for changelog** + - Note what was changed and why + - Prepare changelog entry for job.yml + +### Step 5: Create/Update AGENTS.md (Bespoke Learnings) + +The AGENTS.md file captures project-specific knowledge that helps future agent runs. + +1. **Determine the correct location** + - Place AGENTS.md in the working folder where job outputs live + - This ensures the knowledge is available when working in that context + - If uncertain, place at the project root + +2. **Use file references where possible** + - Instead of duplicating information, reference source files + - This keeps AGENTS.md in sync as the codebase evolves + - Pattern: "See `path/to/file.ext` for [description]" + +3. **AGENTS.md structure**: + +```markdown +# Project Context for [Job Name] + +## Codebase Structure + + +- Project structure: See `README.md` for overview +- API documentation: See `docs/api.md` +- Configuration: See `config/README.md` + +## Conventions + +### Naming Conventions +- [Convention]: See example in `path/to/example.ext:LINE` + +### File Organization +- [Pattern]: Reference `path/to/pattern/` + +## Job-Specific Context + +### [Job Name] + +#### [Step Name] +- [Learning]: Reference `relevant/file.ext` +- [Context]: [Brief explanation with file reference] + +## Known Issues and Workarounds + +- [Issue]: [Workaround with file reference if applicable] + +## Last Updated +- Date: [YYYY-MM-DD] +- From conversation about: [Brief description] +``` + +4. **Writing entries** + - Be concise but specific + - Always prefer file references over inline content + - Use line numbers when referencing specific code: `file.ext:42` + - Group related learnings together + +### Step 6: Update Job Version and Changelog + +If instruction files were modified: + +1. **Bump version in job.yml** + - Patch version (0.0.x) for instruction improvements + - Minor version (0.x.0) if quality criteria changed + +2. **Add changelog entry** + ```yaml + - version: "[new_version]" + changes: "Improved [step] instructions based on execution learnings: [brief description]" + ``` + +### Step 7: Sync and Summarize + +1. **Run deepwork sync** (if instructions were modified) + ```bash + deepwork sync + ``` + +2. **Create learning_summary.md** in the working folder: + ```markdown + # Learning Summary + + ## Job Analyzed + - Job: [job_name] + - Steps executed: [list of steps] + + ## Generalizable Improvements Made + - [Step]: [What was improved] + + ## Bespoke Learnings Captured + - Location: [path to AGENTS.md] + - Entries added: [list of entries] + + ## Files Modified + - [List of files changed] + + ## Recommendations + - [Any additional suggestions] + ``` + +3. **Instruct user to reload** if commands were regenerated + +## File Reference Patterns + +When adding entries to AGENTS.md, prefer these patterns: + +**Good (references)**: +```markdown +- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. +- Error handling pattern: See `src/utils/errors.ts:15-30` +- Configuration schema: Defined in `config/schema.json` +``` + +**Avoid (duplicating)**: +```markdown +- API endpoints should return JSON with this format: { status: ..., data: ... } +- Error handling should use try/catch with custom error classes +- Configuration requires these fields: name, version, ... +``` + +## Quality Criteria + +- Conversation has been analyzed for job executions +- Points of confusion and inefficiency are identified +- Learnings are correctly classified (generalizable vs bespoke) +- Job instructions updated for generalizable improvements +- AGENTS.md created/updated with bespoke learnings +- File references used instead of duplicating content +- AGENTS.md is in the correct working folder +- learning_summary.md documents all changes +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.learn + +Claude: I'll analyze this conversation for learnings from DeepWork job executions. + +**Conversation Analysis** + +I found the following job executions: +1. `/competitive_research.identify_competitors` - Completed +2. `/competitive_research.research_competitors` - Completed with 2 iterations +3. `/competitive_research.comparative_analysis` - Completed + +**Identified Issues** + +1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. + +2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. + +**Classification** + +- Generalizable: Add pricing to research requirements in instructions +- Bespoke: This project focuses on B2B SaaS in the HR tech space + +**Actions Taken** + +1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: + - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements + - Added note about carrying forward industry context from previous step + +2. Created `./competitive_research_output/AGENTS.md`: + ```markdown + # Project Context for Competitive Research + + ## Job-Specific Context + + ### competitive_research + + #### Industry Focus + - Domain: B2B SaaS, HR Technology sector + - See `identify_competitors_output.md` for market definition + + #### Competitors Identified + - Reference: `competitor_list.md` for full details + + ## Last Updated + - Date: 2024-01-15 + - From conversation about: Initial competitive analysis run + ``` + +3. Updated job.yml version to 1.0.1 with changelog entry + +4. Ran `deepwork sync` + +**Summary** + +Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +``` + +## Handling Edge Cases + +**No job executions found**: +- Ask user which job they'd like to analyze +- Or offer to review available jobs + +**Multiple jobs executed**: +- Analyze each job separately +- Create separate AGENTS.md entries or files as appropriate + +**AGENTS.md already exists**: +- Read existing content +- Append new learnings to appropriate sections +- Update "Last Updated" section + +**No issues found**: +- Document what worked well +- Consider if any successful patterns should be added to instructions as examples + +**Sensitive information**: +- Never include secrets, credentials, or PII in AGENTS.md +- Reference config files instead of including values diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md deleted file mode 100644 index 389ce009..00000000 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md +++ /dev/null @@ -1,447 +0,0 @@ -# Refine Existing DeepWork Job - -## Objective - -Help the user modify an existing DeepWork job definition by understanding what they want to change and ensuring the modifications maintain consistency and validity. - -## Task - -Guide the user through refining a job by first understanding their existing job, then what they want to change, and finally implementing those changes safely. - -### Step 1: Select and Load Job - -1. **List available jobs** - - Scan `.deepwork/jobs/` directory for installed jobs - - Display installed jobs with versions and descriptions - - Ask which job to refine - -2. **Load job definition** - - Read `.deepwork/jobs/[job_name]/job.yml` - - Parse and understand the current structure - -3. **Show current structure** - - Display all steps with their names and descriptions - - Show the dependency flow - - Highlight key inputs and outputs - -### Step 2: Understand Desired Changes - -Ask the user what they want to change: - -**Change Options:** -1. Add a new step to the workflow -2. Modify step instructions -3. Change step inputs/outputs -4. Update dependencies between steps -5. Update job metadata (description, version) -6. Remove a step -7. Add or modify stop hooks (quality validation) - -**For each change, ask clarifying questions:** -- Why do they want to make this change? -- How will it improve the workflow? -- Are there dependencies or side effects to consider? - -### Step 3: Make Changes Safely - -Based on the user's selection: - -#### Adding a Step - -1. **Gather step details** (same as define command) - - What does this step accomplish? - - What are the inputs? User parameters or file inputs? - - What outputs does it produce? - - What are the dependencies? - -2. **Determine placement** - - Where should it go in the workflow? - - Before which existing step? - - Or at the end? - -3. **Validate placement** - - Can't depend on later steps if inserted early - - File inputs must come from dependencies - - Check for circular dependencies - -4. **Update files** - - Update `job.yml` with new step - - Create step instructions file in `steps/[step_id].md` - - Prepare changelog entry describing the addition - -#### Modifying Step Instructions - -1. **Select step to modify** - - Show list of steps - - Ask which one to modify - -2. **Understand the change** - - What's not working with current instructions? - - What should be different? - - Show current instructions - -3. **Update instructions** - - Modify `.deepwork/jobs/[job_name]/steps/[step_id].md` - - Keep the same structure (Objective, Task, Process, Output Format, Quality Criteria) - - Prepare changelog entry describing the modification - -#### Changing Inputs/Outputs - -1. **Select step to modify** -2. **Show current inputs and outputs** -3. **Understand the change** - - Adding or removing? - - Why is this needed? - -4. **Validate impact** - - If removing output: check if other steps depend on it (BREAKING CHANGE) - - If adding file input: ensure from_step is in dependencies - - If removing input: ensure it's not critical - -5. **Update job.yml** - - Prepare changelog entry describing the input/output changes - -#### Updating Dependencies - -1. **Select step to modify** -2. **Show current dependency graph** -3. **Understand the change** - - Adding or removing dependency? - - Why? - -4. **Validate** - - Check for circular dependencies - - Ensure all file inputs have matching dependencies - - Ensure dependency chain makes logical sense - -5. **Update job.yml** - - Prepare changelog entry describing the dependency changes - -#### Updating Metadata - -1. **Ask what to change** - - Description? - - Version? - -2. **If version change, explain semantic versioning** - - Major (x.0.0): Breaking changes (removing steps, removing outputs) - - Minor (0.x.0): New features, backwards compatible (adding steps) - - Patch (0.0.x): Bug fixes, improvements - -3. **Update job.yml** - - Prepare changelog entry describing the metadata changes - -#### Removing a Step - -1. **Select step to remove** - -2. **CRITICAL: Validate safety** - - Check if other steps depend on this step - - Check if other steps use outputs from this step - - If dependencies exist: **WARN** and suggest updating dependents first - - This is a BREAKING CHANGE - requires major version bump - -3. **If safe to remove** - - Remove from `job.yml` - - Delete step instructions file - - Suggest version bump - - Prepare changelog entry describing the removal - -#### Adding or Modifying Stop Hooks - -Stop hooks provide quality validation loops that ensure step outputs meet criteria before completing. - -1. **Select step to modify** - - Show list of steps - - Ask which one to add/modify hooks for - -2. **Understand the need** - - What quality criteria should be validated? - - Is the output subjective (use prompt hook) or objective (use script hook)? - - Should validation happen automatically or only on specific conditions? - -3. **Choose hook type** - - **Prompt hooks** (recommended for most cases): - - Best for subjective quality criteria - - AI evaluates the output against criteria - - Example: "Verify the report is comprehensive and well-organized" - ```yaml - stop_hooks: - - prompt: | - Verify the output meets criteria: - 1. Contains all required sections - 2. Analysis is thorough - 3. Recommendations are actionable - ``` - - **Prompt file hooks**: - - For reusable or complex validation criteria - - Stores criteria in a separate markdown file - ```yaml - stop_hooks: - - prompt_file: hooks/quality_check.md - ``` - - **Script hooks**: - - For objective, programmatic validation - - Best for tests, linting, format checking - ```yaml - stop_hooks: - - script: hooks/run_tests.sh - ``` - -4. **Multiple hooks can be combined** - ```yaml - stop_hooks: - - script: hooks/lint.sh # First: objective checks - - prompt: "Verify content quality" # Then: subjective review - ``` - -5. **Update files** - - Add/modify `stop_hooks` array in job.yml - - Create hook files if using prompt_file or script types - - Update step instructions to match quality criteria - - Prepare changelog entry - -6. **Encourage prompt-based hooks** - - They leverage the AI's ability to understand context - - More flexible than rigid script checks - - Can evaluate nuanced quality criteria - -### Step 4: Update Changelog - -After making changes to the job.yml: - -1. **Add a changelog entry** - - Add a new entry to the `changelog` array in the job.yml - - Use the new version number - - List all changes made in this refinement - -2. **Changelog entry format**: - ```yaml - - version: "[new_version]" - changes: "[Description of all changes in this version]" - ``` - -3. **Example changelog entries**: - - "Added step: validate_positioning" - - "Modified step instructions for research_competitors to improve clarity and add quality criteria" - - "Removed step: duplicate_analysis (consolidated into comparative_analysis)" - - "Updated dependencies: positioning_recommendations now depends on validate_positioning" - - "Changed output filename: comparison_matrix.md → comparison_table.md" - - "Added step: validate_positioning; Updated dependencies for positioning_recommendations" - -### Step 5: Validate Changes - -After updating the changelog: - -1. **Review the updated structure** - - Show the complete updated workflow - - Highlight what changed - - Check for consistency - -2. **Validate job definition** - - No circular dependencies - - All file inputs match dependencies - - All step IDs unique - - All outputs defined - -3. **Confirm version update** - - Ensure version was bumped appropriately - - Breaking changes? Major version - - New features? Minor version - - Improvements? Patch version - -### Step 6: Sync and Reload - -1. **Run sync** - ```bash - deepwork sync - ``` - -2. **Reload commands** - - Instruct user to run `/reload` or restart session - -3. **Provide summary** - - Show what changed - - List updated files - - Display the changelog entry - - Explain next steps - -## Safe Modification Patterns - -Guide users toward safe changes: - -### Safe Changes (Always OK) -- Adding steps at the end with new outputs -- Updating step instructions (content only) -- Changing job description -- Adding user inputs to a step -- Adding outputs (not removing) -- Patch version bumps - -### Potentially Breaking Changes (Warn User) -- Removing steps -- Removing outputs -- Removing inputs -- Changing dependencies -- Renaming outputs (other steps may reference them) -- Requires major or minor version bump - -### Always Validate -- Circular dependencies after any dependency change -- File inputs match dependencies after any change -- Step IDs remain unique -- At least one output per step - -## Example Dialog - -``` -Claude: I'll help you refine an existing job. Here are your installed jobs: - -1. competitive_research v1.0.0 - Systematic competitive analysis workflow -2. blog_post v1.0.0 - Blog post creation workflow - -Which job would you like to refine? - -User: 1 - -Claude: Loading competitive_research v1.0.0... - -Current structure: -- Step 1: identify_competitors - Identify 5-7 competitors in target market -- Step 2: research_competitors - Deep research on each competitor -- Step 3: comparative_analysis - Side-by-side comparison matrix -- Step 4: positioning_recommendations - Strategic positioning report - -What would you like to change? -1. Add a new step -2. Modify step instructions -3. Change inputs/outputs -4. Update dependencies -5. Update job metadata -6. Remove a step - -User: 1 - -Claude: Great! Let's add a new step. First, help me understand: - -1. What should this new step accomplish? -2. Where should it fit in the workflow? - - Should it go between existing steps or at the end? - -User: I want to add a step that validates our product positioning before the final recommendations. It should go between step 3 and step 4. - -Claude: Excellent idea. So this would be: -- Step 4: validate_positioning -- Step 5: positioning_recommendations (renumbered) - -For this validation step: -1. What inputs does it need? I assume it needs the comparison_matrix.md from step 3? -2. What should it output? -3. What exactly should this validation check for? - -User: Yes, it needs the comparison matrix. It should output a validation_report.md that identifies gaps in our positioning. - -Claude: Perfect. Let me confirm the details: - -**New Step: validate_positioning** -- Name: "Validate Product Positioning" -- Description: "Identify gaps and opportunities in current positioning" -- Inputs: comparison_matrix.md (from comparative_analysis step) -- Outputs: validation_report.md -- Dependencies: comparative_analysis -- Position: Between step 3 and 4 - -Should the positioning_recommendations step also use the validation_report.md as input? - -User: Yes, definitely - -Claude: Great! So I'll also update the positioning_recommendations step to include validation_report.md as an input and add validate_positioning as a dependency. - -This is a new feature, so I'll bump the version to 1.1.0 (minor version). - -Creating the new step... ✓ - -Updated files: -- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0, updated changelog) -- .deepwork/jobs/competitive_research/steps/validate_positioning.md (created) - -Changelog entry added: -```yaml -- version: "1.1.0" - changes: "Added step: validate_positioning between comparative_analysis and positioning_recommendations; Updated dependencies for positioning_recommendations" -``` - -Now run: -```bash -deepwork sync -``` - -Then reload your session and you'll have: -- /competitive_research.validate_positioning (new!) -- All other commands updated -``` - -## Validation Rules - -Enforce the same rules as job definition: -- Job name: lowercase, underscores -- Version: semantic versioning -- Step IDs: unique within job -- Dependencies: must reference existing step IDs -- File inputs: `from_step` must be in dependencies -- At least one output per step -- No circular dependencies - -## Error Handling - -If issues arise, provide clear guidance: -- **Dependency conflict**: "Step X depends on step Y which you're trying to remove. You must update step X first, or remove both steps." -- **Circular dependency**: "Adding this dependency would create a cycle: A → B → C → A. Please choose a different dependency structure." -- **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies. I'll add Y to the dependencies." -- **Breaking change**: "Removing this output is a breaking change. Other steps depend on it. I recommend against this change unless you update the dependent steps first." - -## Changelog Entry Format - -Instead of creating a separate refinement_summary.md file, add the changes directly to the job.yml changelog section. This creates a permanent version history within the job definition itself. - -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -**Add to the `changelog` array**: - -```yaml -changelog: - - version: "1.0.0" - changes: "Initial job creation" - - version: "[new_version]" - changes: "[Concise description of all changes in this version]" -``` - -**Guidelines for changelog entries**: -- Be concise but descriptive -- Use action verbs (Added, Modified, Removed, Updated, Changed, Fixed) -- Reference specific step names when relevant -- For breaking changes, prefix with "BREAKING:" -- If multiple changes, separate with semicolons or use clear phrasing - -**Examples**: -- "Added step: validate_positioning between comparative_analysis and positioning_recommendations" -- "Modified step instructions for research_competitors to improve clarity and add quality criteria" -- "Removed step: duplicate_analysis (consolidated into comparative_analysis)" -- "Updated dependencies: positioning_recommendations now depends on validate_positioning" -- "Changed output filename: comparison_matrix.md → comparison_table.md" -- "BREAKING: Removed output file shared_data.json from identify_competitors step" -- "Fixed circular dependency between steps A and B" -- "Updated job description to reflect new validation phase" -- "Added validate_positioning step; Updated dependencies for positioning_recommendations" - -## Quality Criteria - -- Changes maintain job consistency -- Dependencies are logically valid -- Version bump follows semantic versioning -- No circular dependencies introduced -- User understands impact of changes -- Breaking changes are clearly communicated From bb4e1a62d6a89418736a9521bcf99c145db693be Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Jan 2026 22:47:10 +0000 Subject: [PATCH 2/3] Improve learn command with conciseness criteria and shared file extraction Updates to the learn command: - Simplified working folder identification (use conversation history, fall back to git diff) - Added quality criteria for instruction conciseness (no redundancy/verbosity) - Added Step 4b for extracting shared/lengthy content into referenced files - Instructions can now reference shared files in steps/shared/ directory This helps keep job instructions maintainable and DRY. --- .claude/commands/deepwork_jobs.learn.md | 66 ++++++++++++++----- .deepwork/jobs/deepwork_jobs/job.yml | 12 ++-- .deepwork/jobs/deepwork_jobs/steps/learn.md | 42 ++++++++++-- .gemini/commands/deepwork_jobs/learn.toml | 42 ++++++++++-- .../standard_jobs/deepwork_jobs/job.yml | 12 ++-- .../deepwork_jobs/steps/learn.md | 42 ++++++++++-- 6 files changed, 176 insertions(+), 40 deletions(-) diff --git a/.claude/commands/deepwork_jobs.learn.md b/.claude/commands/deepwork_jobs.learn.md index 6352b632..9453f52f 100644 --- a/.claude/commands/deepwork_jobs.learn.md +++ b/.claude/commands/deepwork_jobs.learn.md @@ -14,11 +14,13 @@ hooks: 1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? 2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? 3. **Instructions Improved**: Were job instructions updated to address identified issues? - 4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? - 5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? - 6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? - 7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? - 8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? + 4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity? + 5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files? + 6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? + 7. **File References Used**: Do AGENTS.md entries reference other files where appropriate? + 8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? + 9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? + 10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. @@ -79,9 +81,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Note the order of execution 2. **Identify the working folder** - - Find where outputs were created during job execution - - This is typically specified in the job's working directory - - Common patterns: project root, `./output/`, or job-specific directories + - Should be clear from conversation history where work was done + - If unclear, run `git diff` to see where changes were made on the branch 3. **If no job was specified**, ask the user: - "Which DeepWork job would you like me to learn from?" @@ -150,15 +151,46 @@ For each generalizable learning: - Clarify ambiguous instructions - Update quality criteria if needed -3. **Preserve instruction structure** +3. **Keep instructions concise** + - Avoid redundancy - don't repeat the same guidance in multiple places + - Be direct - remove verbose explanations that don't add value + - Prefer bullet points over paragraphs where appropriate + +4. **Preserve instruction structure** - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - Add to appropriate sections rather than restructuring - Maintain consistency with other steps -4. **Track changes for changelog** +5. **Track changes for changelog** - Note what was changed and why - Prepare changelog entry for job.yml +### Step 4b: Extract Shared Content into Referenced Files + +Review all instruction files for the job and identify content that: +- Appears in multiple step instructions (duplicated) +- Is lengthy and could be extracted for clarity +- Would benefit from being maintained in one place + +**Extract to shared files:** + +1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` + - `conventions.md` - Coding/formatting conventions used across steps + - `examples.md` - Common examples referenced by multiple steps + - `schemas.md` - Data structures or formats used throughout + +2. **Reference from instructions** using markdown includes or explicit references: + ```markdown + ## Conventions + + Follow the conventions defined in `shared/conventions.md`. + ``` + +3. **Benefits of extraction:** + - Single source of truth - update once, applies everywhere + - Shorter instruction files - easier to read and maintain + - Consistent guidance across steps + ### Step 5: Create/Update AGENTS.md (Bespoke Learnings) The AGENTS.md file captures project-specific knowledge that helps future agent runs. @@ -285,6 +317,8 @@ When adding entries to AGENTS.md, prefer these patterns: - Points of confusion and inefficiency are identified - Learnings are correctly classified (generalizable vs bespoke) - Job instructions updated for generalizable improvements +- Instructions are concise - no redundancy or unnecessary verbosity +- Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content - AGENTS.md is in the correct working folder @@ -415,11 +449,13 @@ Verify the learning process meets ALL quality criteria before completing: 1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? 2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? 3. **Instructions Improved**: Were job instructions updated to address identified issues? -4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? -5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? -6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? -7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? -8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? +4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity? +5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files? +6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? +7. **File References Used**: Do AGENTS.md entries reference other files where appropriate? +8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? +9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? +10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 7c6b81c1..4bb86566 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -95,11 +95,13 @@ steps: 1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? 2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? 3. **Instructions Improved**: Were job instructions updated to address identified issues? - 4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? - 5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? - 6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? - 7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? - 8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? + 4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity? + 5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files? + 6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? + 7. **File References Used**: Do AGENTS.md entries reference other files where appropriate? + 8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? + 9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? + 10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md index b00f6610..5a74ed78 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -18,9 +18,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Note the order of execution 2. **Identify the working folder** - - Find where outputs were created during job execution - - This is typically specified in the job's working directory - - Common patterns: project root, `./output/`, or job-specific directories + - Should be clear from conversation history where work was done + - If unclear, run `git diff` to see where changes were made on the branch 3. **If no job was specified**, ask the user: - "Which DeepWork job would you like me to learn from?" @@ -89,15 +88,46 @@ For each generalizable learning: - Clarify ambiguous instructions - Update quality criteria if needed -3. **Preserve instruction structure** +3. **Keep instructions concise** + - Avoid redundancy - don't repeat the same guidance in multiple places + - Be direct - remove verbose explanations that don't add value + - Prefer bullet points over paragraphs where appropriate + +4. **Preserve instruction structure** - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - Add to appropriate sections rather than restructuring - Maintain consistency with other steps -4. **Track changes for changelog** +5. **Track changes for changelog** - Note what was changed and why - Prepare changelog entry for job.yml +### Step 4b: Extract Shared Content into Referenced Files + +Review all instruction files for the job and identify content that: +- Appears in multiple step instructions (duplicated) +- Is lengthy and could be extracted for clarity +- Would benefit from being maintained in one place + +**Extract to shared files:** + +1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` + - `conventions.md` - Coding/formatting conventions used across steps + - `examples.md` - Common examples referenced by multiple steps + - `schemas.md` - Data structures or formats used throughout + +2. **Reference from instructions** using markdown includes or explicit references: + ```markdown + ## Conventions + + Follow the conventions defined in `shared/conventions.md`. + ``` + +3. **Benefits of extraction:** + - Single source of truth - update once, applies everywhere + - Shorter instruction files - easier to read and maintain + - Consistent guidance across steps + ### Step 5: Create/Update AGENTS.md (Bespoke Learnings) The AGENTS.md file captures project-specific knowledge that helps future agent runs. @@ -224,6 +254,8 @@ When adding entries to AGENTS.md, prefer these patterns: - Points of confusion and inefficiency are identified - Learnings are correctly classified (generalizable vs bespoke) - Job instructions updated for generalizable improvements +- Instructions are concise - no redundancy or unnecessary verbosity +- Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content - AGENTS.md is in the correct working folder diff --git a/.gemini/commands/deepwork_jobs/learn.toml b/.gemini/commands/deepwork_jobs/learn.toml index 4f3c412e..39e90537 100644 --- a/.gemini/commands/deepwork_jobs/learn.toml +++ b/.gemini/commands/deepwork_jobs/learn.toml @@ -50,9 +50,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Note the order of execution 2. **Identify the working folder** - - Find where outputs were created during job execution - - This is typically specified in the job's working directory - - Common patterns: project root, `./output/`, or job-specific directories + - Should be clear from conversation history where work was done + - If unclear, run `git diff` to see where changes were made on the branch 3. **If no job was specified**, ask the user: - "Which DeepWork job would you like me to learn from?" @@ -121,15 +120,46 @@ For each generalizable learning: - Clarify ambiguous instructions - Update quality criteria if needed -3. **Preserve instruction structure** +3. **Keep instructions concise** + - Avoid redundancy - don't repeat the same guidance in multiple places + - Be direct - remove verbose explanations that don't add value + - Prefer bullet points over paragraphs where appropriate + +4. **Preserve instruction structure** - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - Add to appropriate sections rather than restructuring - Maintain consistency with other steps -4. **Track changes for changelog** +5. **Track changes for changelog** - Note what was changed and why - Prepare changelog entry for job.yml +### Step 4b: Extract Shared Content into Referenced Files + +Review all instruction files for the job and identify content that: +- Appears in multiple step instructions (duplicated) +- Is lengthy and could be extracted for clarity +- Would benefit from being maintained in one place + +**Extract to shared files:** + +1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` + - `conventions.md` - Coding/formatting conventions used across steps + - `examples.md` - Common examples referenced by multiple steps + - `schemas.md` - Data structures or formats used throughout + +2. **Reference from instructions** using markdown includes or explicit references: + ```markdown + ## Conventions + + Follow the conventions defined in `shared/conventions.md`. + ``` + +3. **Benefits of extraction:** + - Single source of truth - update once, applies everywhere + - Shorter instruction files - easier to read and maintain + - Consistent guidance across steps + ### Step 5: Create/Update AGENTS.md (Bespoke Learnings) The AGENTS.md file captures project-specific knowledge that helps future agent runs. @@ -256,6 +286,8 @@ When adding entries to AGENTS.md, prefer these patterns: - Points of confusion and inefficiency are identified - Learnings are correctly classified (generalizable vs bespoke) - Job instructions updated for generalizable improvements +- Instructions are concise - no redundancy or unnecessary verbosity +- Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content - AGENTS.md is in the correct working folder diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 7c6b81c1..4bb86566 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -95,11 +95,13 @@ steps: 1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions? 2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies? 3. **Instructions Improved**: Were job instructions updated to address identified issues? - 4. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? - 5. **File References Used**: Do AGENTS.md entries reference other files where appropriate? - 6. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? - 7. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? - 8. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? + 4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity? + 5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files? + 6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md? + 7. **File References Used**: Do AGENTS.md entries reference other files where appropriate? + 8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job? + 9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md? + 10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified? If ANY criterion is not met, continue working to address it. If ALL criteria are satisfied, include `✓ Quality Criteria Met` in your response. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index b00f6610..5a74ed78 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -18,9 +18,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Note the order of execution 2. **Identify the working folder** - - Find where outputs were created during job execution - - This is typically specified in the job's working directory - - Common patterns: project root, `./output/`, or job-specific directories + - Should be clear from conversation history where work was done + - If unclear, run `git diff` to see where changes were made on the branch 3. **If no job was specified**, ask the user: - "Which DeepWork job would you like me to learn from?" @@ -89,15 +88,46 @@ For each generalizable learning: - Clarify ambiguous instructions - Update quality criteria if needed -3. **Preserve instruction structure** +3. **Keep instructions concise** + - Avoid redundancy - don't repeat the same guidance in multiple places + - Be direct - remove verbose explanations that don't add value + - Prefer bullet points over paragraphs where appropriate + +4. **Preserve instruction structure** - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - Add to appropriate sections rather than restructuring - Maintain consistency with other steps -4. **Track changes for changelog** +5. **Track changes for changelog** - Note what was changed and why - Prepare changelog entry for job.yml +### Step 4b: Extract Shared Content into Referenced Files + +Review all instruction files for the job and identify content that: +- Appears in multiple step instructions (duplicated) +- Is lengthy and could be extracted for clarity +- Would benefit from being maintained in one place + +**Extract to shared files:** + +1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/` + - `conventions.md` - Coding/formatting conventions used across steps + - `examples.md` - Common examples referenced by multiple steps + - `schemas.md` - Data structures or formats used throughout + +2. **Reference from instructions** using markdown includes or explicit references: + ```markdown + ## Conventions + + Follow the conventions defined in `shared/conventions.md`. + ``` + +3. **Benefits of extraction:** + - Single source of truth - update once, applies everywhere + - Shorter instruction files - easier to read and maintain + - Consistent guidance across steps + ### Step 5: Create/Update AGENTS.md (Bespoke Learnings) The AGENTS.md file captures project-specific knowledge that helps future agent runs. @@ -224,6 +254,8 @@ When adding entries to AGENTS.md, prefer these patterns: - Points of confusion and inefficiency are identified - Learnings are correctly classified (generalizable vs bespoke) - Job instructions updated for generalizable improvements +- Instructions are concise - no redundancy or unnecessary verbosity +- Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content - AGENTS.md is in the correct working folder From 777124e6fac700faba73152cc36e8e4909053e0c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Jan 2026 00:04:50 +0000 Subject: [PATCH 3/3] Update tests to check for learn command instead of refine --- tests/integration/test_install_flow.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/integration/test_install_flow.py b/tests/integration/test_install_flow.py index e4f51d3a..09c97ffc 100644 --- a/tests/integration/test_install_flow.py +++ b/tests/integration/test_install_flow.py @@ -42,7 +42,7 @@ def test_install_with_claude(self, mock_claude_project: Path) -> None: # Verify core commands were created claude_dir = mock_claude_project / ".claude" / "commands" assert (claude_dir / "deepwork_jobs.define.md").exists() - assert (claude_dir / "deepwork_jobs.refine.md").exists() + assert (claude_dir / "deepwork_jobs.learn.md").exists() # Verify command content define_command = (claude_dir / "deepwork_jobs.define.md").read_text() @@ -120,7 +120,7 @@ def test_install_is_idempotent(self, mock_claude_project: Path) -> None: claude_dir = mock_claude_project / ".claude" / "commands" assert (claude_dir / "deepwork_jobs.define.md").exists() - assert (claude_dir / "deepwork_jobs.refine.md").exists() + assert (claude_dir / "deepwork_jobs.learn.md").exists() class TestCLIEntryPoint: