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.