Design before you code - explore problems, search existing knowledge, form hypotheses, and visualize before implementing.
STOP. Code is the last step, not the first.
knots search "topic"
knots search "topic" --section findings # Search within specific sections
knots search "decision" --section rationale # Fuzzy: matches "Rationale"
knots recommend --issue <id>
| Question | If Yes |
|---|---|
| Does a solution already exist? |
| Use it or learn from it |
| Has this been tried before? | Read what was learned |
| Are there constraints that apply? | Honor them |
Tip: Use --section to target specific parts of artifacts (e.g., Findings, Decision, Problem).
| Element | Question |
|---|---|
| Observable | What symptom are you seeing? |
| Impact | Why does this matter? |
| Scope | What's affected? |
Create at least one:
| Hypothesis | Test | Result |
|---|---|---|
| Rate limit is per-user | 2 users, 100 calls each | ✓ confirmed |
| Rate limit is per-IP | Same IP, diff users | ✗ rejected |
| Rule | Consequence |
|---|---|
| Search knowledge before assuming none exists | Duplicate work, miss constraints |
| State problem before proposing solution | Solve wrong problem |
| Check strategic alignment before implementing | Wasted effort on deprioritized work |
| Preference | Override When |
|---|---|
| Draw diagram before coding | Trivial/well-understood change |
| Create investigation artifact | Simple bug with obvious fix |
| Form multiple hypotheses | Single clear root cause |
Before implementation, answer:
User Input → Validation → Processing → Storage
↓ ↓
[errors] [metrics]
┌─────────┐ start ┌──────────┐ done ┌──────────┐
│ idle │ ──────────→ │ running │ ─────────→ │ complete │
└─────────┘ └──────────┘ └──────────┘
↑ │
└───────── cancel ──────┘
| Option | Pros | Cons | Effort |
|-----------|---------------|---------------|--------|
| Redis | Fast, mature | Memory-bound | Low |
| Postgres | Durable, SQL | Slower | Medium |
1. Search existing knowledge
↓
2. State the problem clearly
↓
3. Visualize (diagram, table, mockup)
↓
4. Hypothesize (if investigating)
↓
5. ITERATE: Review and refine (see below)
↓
6. Document (knots new investigation "...")
↓
7. Only then → implement
First drafts are rarely best. Before implementing, revisit your ideation.
After completing initial ideation, ask:
| Question | If No → Action |
|---|---|
| Is the problem statement precise enough? | Sharpen scope, remove ambiguity |
| Did I miss any existing knowledge? | Search again with new terms learned |
| Does my diagram capture all flows? | Add missing edges, error paths |
| Are there simpler alternatives? | Add to comparison table |
| What would a critic say? | Steel-man the objections |
| Situation | Iterations |
|---|---|
| Trivial bug fix | 0 (skip refinement) |
| Standard feature | 1 pass (quick review) |
| Architectural decision | 2+ passes (sleep on it if possible) |
| Multi-system integration | 2+ passes + peer review |
## Second-Pass Review
- [ ] Problem statement: Precise, scoped, unambiguous?
- [ ] Diagram: All paths including errors?
- [ ] Alternatives: At least 2 options considered?
- [ ] Constraints: All known constraints listed?
- [ ] Objections: What could go wrong?
- [ ] Simpler: Is there a simpler approach?
The test: "If I explain this to a skeptic, where would they poke holes?"
When exploring a problem, produce:
## Problem
API returns 429 under load (>100 req/min per user)
## Prior Knowledge
- K-2026-0042: Rate limiting decision (Redis token bucket)
- No existing investigation on current limits
## Diagram
Client → API Gateway → Rate Limiter → Backend
↓ ↓
[429] [metrics]
## Hypotheses
1. Per-user limit ✓ confirmed
2. Per-IP limit ✗ rejected
## Recommendation
Increase limit to 200/min or implement tiered limits.
| ❌ Don't | ✅ Do |
|---|---|
| Start coding immediately | Spend 5 min searching first |
| Skip knowledge search "probably new" | Always check |
| Jump from "what" to "how" | Stop at "why" first |
| Assume you understand the problem | State it explicitly |
| Conflate multiple problems | One problem, one solution |
| Purpose | Command |
|---|---|
| Search knowledge | knots search "topic" |
| Search in section | knots search "topic" --section findings |
| Get recommendations | knots recommend --issue <id> |
| Report search issues | knots feedback --query "x" --reason "low-signal" |
| Quick capture | knots crumb "observation" |
| Durable investigation | knots new investigation "title" |
| Check alignment | knots session |
| One-line syntax | knots <cmd> --usage |