orchestrating-knowledge-workflows

# Orchestrating Knowledge Workflows Guide for managing the complete plan-build-improve cycle when making knowledge base updates. The spec-as-contract pattern ensures review before implementation. ## Instructions ### Step 1: Plan Stage - Create Specification Before any implementation, create a spec document: 1. **Analyze the requirement** - Identify core concepts and learning - Search existing content with Grep/Glob to assess coverage - Determine entry strategy: new file vs extend existing 2. **Write spec to `.claude/.cache/specs/knowledge/{slug}-spec.md`** ```markdown # Spec: {Title} ## Requirement {Original user requirement} ## Analysis - Existing coverage: {files that touch this topic} - Gap identified: {what's missing} - Entry strategy: {new | extend | journal} ## Plan - Target file: {absolute path} - Changes: {bullet list of content additions} - Cross-references: {other files to update} - Voice notes: {tone guidance from existing content} ## Verification - [ ] Content aligns with STYLE_GUIDE.md - [ ] Frontmatter updated (last_updated, tags) - [ ] Cross-references added ``` ### Step 2: Review Stage - User Approval Present spec to user before proceeding: - Show spec location and summary - Ask: "Ready to proceed with implementation?" - Options: Yes / No (review first) / Edit spec then continue **If user declines**: Save spec path, report how to resume later. This is valid - not an error. ### Step 3: Build Stage - Implement from Spec Execute the spec faithfully: 1. **Load specification** - Read the spec file 2. **Review target context** - Read existing content if extending 3. **Implement content changes** - New file: Create with proper frontmatter - Extend: Add sections preserving voice - Journal: Add dated entry 4. **Add cross-references** - Update related files 5. **Update metadata** - Set `last_updated` in frontmatter 6. **Verify** - Check spec verification items ### Step 4: Improve Stage - Update Expert Knowledge After successful build, extract learnings: 1. **Review what was built** - Compare spec to implementation 2. **Extract patterns** - What worked well? - What was harder than expected? - Any anti-patterns discovered? 3. **Update expertise** - Record learnings for future workflows 4. **Document anti-patterns** - What to avoid next time **Note**: Improve stage is optional. If it fails, log but don't fail overall workflow. ### Step 5: Report Results ```markdown ## Knowledge Workflow Complete **Requirement:** {original requirement} ### Stages | Stage | Status | Output | |-------|--------|--------| | Plan | Complete | {spec_path} | | Build | Complete | {file_count} files modified | | Improve | Complete/Skipped | {expertise notes} | ### Files Modified - {list of absolute paths with brief descriptions} ### Specification Saved at: {spec_path} Resume later with: "Build from spec at {spec_path}" ``` ## Key Principles **Spec-as-Contract Pattern** - Spec is the single source of truth for what to build - User reviews spec before implementation begins - Changes to scope require spec update first - Spec persists even if build fails (can retry) **Sequential Execution** - Plan -> Review -> Build -> Improve runs in order - Each stage depends on previous stage output - Don't parallelize this workflow **User Control Points** - Review after plan, before build - User can edit spec and continue - Declining to proceed is valid outcome **Graceful Degradation** - Build failure: Preserve spec, suggest retry - Improve failure: Log but don't fail workflow - Partial success is reported, not hidden ## Examples ### Example 1: Capture new insight ``` User: "Add insight about prompt caching to chapter 4" Plan: - Grep chapter 4 for existing caching content - Determine best section to extend - Write spec with specific additions Build: - Read target section - Add caching insight preserving voice - Update frontmatter Report: "Added to chapters/4-context/2-context-strategies.md" ``` ### Example 2: New mental model ``` User: "Create entry for 'specs as source code' mental model" Plan: - Check chapter 8 structure - Identify next section number - Write spec for new file Build: - Create chapters/8-mental-models/3-specs-as-source-code.md - Add proper frontmatter - Write content following STYLE_GUIDE Report: "Created new entry with frontmatter order 3.8.3" ``` ### Example 3: Resume from spec ``` User: "Build from spec at .claude/.cache/specs/knowledge/prompt-caching-spec.md" Skip plan stage (spec exists) Skip review stage (user explicitly requesting build) Execute build from spec Run improve stage ``` ### Example 4: User declines at review ``` Plan stage completes, spec written User: "No, stop here - I'll review the spec first" Report: - Spec location: {path} - Resume with: "Build from spec at {path}" - Workflow paused (valid outcome) ```