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

1. 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 STYLEGUIDE.md - [ ] Frontmatter updated (lastupdated, 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

1. Add cross-references - Update related files
2. Update metadata - Set last_updated in frontmatter
3. 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?

1. Update expertise - Record learnings for future workflows
2. 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

## 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)