103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
# 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.
|