cc-os/plugins/cc-architect/references/knowledge-philosophy.md

# Knowledge Philosophy

How to decide what to document in plugins, skills, and workflows.

## Core Principle: Trust AI Training First

AI models know frameworks, best practices, and domain knowledge from training. Don't re-document what they already know.

**Examples of what NOT to document:**
- What Nielsen's 10 heuristics mean
- How WCAG guidelines work
- Standard programming patterns
- Framework APIs and conventions

**What TO document:**
- Rubrics (what to evaluate, severity scales)
- Templates (output formats, task file structures)
- Process steps (sequence of actions, decision points)
- Your specific conventions (naming, file locations)

## Decision Framework

### When to add documentation

Only add explicit documentation when:
1. **Consistent failure** - AI repeatedly gets something wrong
2. **Output variance** - Results vary significantly across runs
3. **Specific rubric needed** - You need consistent scoring/evaluation
4. **Custom template required** - Output must match a specific format
5. **Non-obvious convention** - Your codebase has conventions AI can't infer

### When NOT to add documentation

Skip documentation when:
- AI already knows it from training
- It's explaining theory rather than specifying process
- It's describing a framework rather than applying it
- A quick inline hint would suffice

## Iterate to Specificity

**Start minimal.** Run the skill/workflow. Observe what the AI gets wrong.

**Add incrementally.** Each addition should be:
- The minimum change needed to fix the observed problem
- Targeted at the specific failure, not general improvement
- Testable (you can verify it fixed the issue)

**Resist preemptive documentation.** Don't document "just in case." Document when you have evidence it's needed.

## Workflow Document Formula

Workflow documents should contain:

```
Rubric       + Template      + Process Steps
(what to     + (output       + (sequence of
evaluate)     format)         actions)
```

They should NOT contain:

```
Theory       + Explanations  + Framework descriptions
(why it      + (how it       + (what the framework
matters)       works)          is)
```

## Guidance Levels

| Level | What to specify | What to delegate |
|-------|-----------------|------------------|
| Role/Orchestrator | What workflows to run, when to synthesize, what to present | How workflows execute their evaluations |
| Workflow | What to evaluate, output format, severity scale | How to apply the framework, what the framework means |
| Subagent execution | (nothing - receives workflow doc) | Everything about execution |

## Anti-Patterns

### The Encyclopedia
**Wrong:** 500-line reference doc explaining a framework.
**Right:** 50-line doc with checklist, severity scale, and output template.

### Preemptive Specification
**Wrong:** Documenting every edge case before seeing if AI handles them.
**Right:** Running the skill, noting failures, adding targeted fixes.

### Inline Theory
**Wrong:** Workflow doc starts with "Nielsen's heuristics were developed in 1994..."
**Right:** Workflow doc starts with "Evaluate against these 10 heuristics:"

### Copy-Paste Documentation
**Wrong:** Duplicating framework descriptions from the web.
**Right:** Referencing what AI knows, specifying only your application of it.

## Practical Test

Before adding documentation, ask:

1. **Would a senior AI researcher need this written down?** If they'd know it from training, skip it.
2. **Is this a rubric, template, or process step?** If not, probably skip it.
3. **Did I observe a failure this fixes?** If not, wait until you do.
4. **Is this the minimum change needed?** If not, reduce scope.