---
phase: 10-user-guide-content
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - docs/paradigms.md
autonomous: true
requirements:
  - UGDE-02

must_haves:
  truths:
    - "A reader can identify which paradigm (second-brain vs knowledge garden) applies to their situation using a comparison table"
    - "A reader can follow 2-3 concrete command sequence scenarios per paradigm and see expected outcomes"
    - "A reader understands that the paradigms are non-exclusive and can coexist in one vault"
    - "A reader gets scenario-based 'choose your path' guidance (e.g., 'I want to research a new technology → use second-brain capture-first')"
  artifacts:
    - path: "docs/paradigms.md"
      provides: "Comprehensive paradigm comparison guide"
      min_lines: 160
      contains:
        - "## Second-Brain vs Knowledge Garden"
        - "Choose Your Path"
        - "second-brain"
        - "knowledge garden"
        - "ztlctl supports both"
  key_links:
    - from: "docs/paradigms.md"
      to: "docs/concepts.md"
      via: "inline link"
      pattern: "concepts\\.md"
    - from: "docs/paradigms.md"
      to: "docs/tutorial.md"
      via: "next steps section"
      pattern: "tutorial\\.md"
---

<objective>
Expand docs/paradigms.md from its current 72-line terse overview into a comprehensive 160+ line comparison guide that helps readers choose between second-brain and knowledge-garden approaches, understand how each maps to ztlctl commands, and follow concrete scenario walkthroughs.

Purpose: The current paradigms.md correctly describes the two-layer model but gives readers no decision guidance. A knowledge worker landing on this page cannot tell which paradigm fits their situation or what a real workflow looks like end-to-end.

Output: docs/paradigms.md rewritten as a walkthrough guide with comparison table, "choose your path" guidance, 2-3 concrete scenarios per paradigm (with full command sequences and expected output), and an explanation that the paradigms coexist.
</objective>

<execution_context>
@/Users/shparki/.claude/get-shit-done/workflows/execute-plan.md
@/Users/shparki/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/10-user-guide-content/10-CONTEXT.md
@.planning/phases/10-user-guide-content/10-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Expand paradigms.md into a comprehensive comparison guide</name>
  <files>docs/paradigms.md</files>

  <read_first>
    - docs/paradigms.md — current 72-line content (foundation to expand, not replace)
    - docs/tutorial.md — tone and depth reference (step-by-step, code blocks, expected outcome notes)
    - docs/concepts.md — terminology reference for content types (note, reference, task, garden seed)
  </read_first>

  <action>
Enhance docs/paradigms.md from its current 72 lines to a 160+ line comprehensive guide. Keep the existing two-layer model framing as the structural backbone but add all missing content. Follow tutorial.md's tone: short sentence → code block → brief outcome note.

**Document structure to produce (in order):**

1. **Intro paragraph** (expand from current opening) — explain the two-layer model in 3-4 sentences, anchor it to real knowledge work, mention that second-brain and knowledge-garden are complementary not competing.

2. **Second-Brain vs Knowledge Garden: At a Glance** — comparison table with these exact rows:

   | Dimension | Second-Brain (Capture Layer) | Knowledge Garden (Enrichment Layer) |
   |-----------|------------------------------|--------------------------------------|
   | Primary question | "What did I learn?" | "What do I understand?" |
   | Capture style | Broad, fast, reference-driven | Selective, slow, insight-driven |
   | Content types | Notes, references, tasks, ingested sources | Garden seeds, budding notes, evergreen notes |
   | Organization | Topic routing, session batching | Maturity tiers, backlink structure |
   | Enrichment | Automated (reweave, sessions) | Human-led (Obsidian, dashboard review) |
   | ztlctl commands | `create`, `ingest`, `session`, `query search` | `garden seed`, `update --maturity`, `export dashboard`, `query packet --mode review` |
   | Agent role | Agent captures, synthesizes, triages | Agent assists conversationally, does not garden |

3. **Choose Your Path** section — scenario-based guidance using this exact format:

   **"I want to research a new technology or topic"**
   → Second-brain capture-first approach
   - Start a session, ingest sources, create synthesis notes, let reweave connect them
   - Command sequence: (see scenario 1 below)

   **"I have captured material and want to deepen my understanding"**
   → Knowledge garden enrichment-first approach
   - Promote seed notes to budding, review stale content, tend connections manually
   - Command sequence: (see scenario 2 below)

   **"I want both — capture now, tend later"**
   → They coexist by design. Capture in the machine layer (notes/, ops/), tend in the garden layer (garden/). ztlctl never indexes or mutates garden/ content.

4. **Scenario 1: Researching a New Technology (Second-Brain Approach)** with these exact commands and annotations:

   ```bash
   # Start a focused research session
   ztlctl agent session start "oauth security"

   # Ingest sources as references
   ztlctl ingest text "RFC 6749 notes" --stdin --as reference --tags "auth/oauth"

   # Create synthesis notes as understanding develops
   ztlctl create note "OAuth 2.0 threat model" \
     --tags "auth/oauth,security" \
     --topic auth

   # Build a learning packet from captured material
   ztlctl query packet --topic auth --mode learn

   # Draft a synthesis note from the packet
   ztlctl query draft --topic auth --target note

   # Close session — triggers reweave, orphan sweep, and integrity check automatically
   ztlctl agent session close --summary "Mapped OAuth threat surface"
   ```

   Add annotation: "At session close, ztlctl automatically runs cross-session reweave to connect the new notes, an orphan sweep to link any isolated notes, and an integrity check. No manual step needed."

5. **Scenario 2: Tending Existing Knowledge (Knowledge-Garden Approach)** with these exact commands:

   ```bash
   # Surface seed notes waiting for enrichment
   ztlctl query list --maturity seed --sort recency

   # Review the work queue for stale or actionable items
   ztlctl query work-queue

   # Get a review packet for the topic you're tending
   ztlctl query packet --topic auth --mode review

   # Promote a note as understanding deepens
   ztlctl update ZTL-0001 --maturity budding

   # Export a dashboard for visual review in Obsidian
   ztlctl export dashboard --viewer obsidian --output ./dashboard
   ```

   Add annotation: "Garden work happens in Obsidian (the garden/ directory) or directly via `ztlctl update`. The exported dashboard is a review workbench — machine-layer signals to guide where human tending is most valuable, not a mirror of garden/ state."

6. **Scenario 3: Agent-Assisted Hybrid (Both Paradigms)** — short scenario (3-4 commands) showing agent captures in machine layer, human tends in garden layer:

   ```bash
   # Agent captures research in the machine layer
   ztlctl create note "Distributed consensus trade-offs" --tags "systems/consensus" --topic systems

   # Human reviews agent-captured seeds and promotes them
   ztlctl query list --maturity seed --sort recency
   ztlctl update ZTL-0042 --maturity budding

   # Human tends connections in Obsidian's garden/ layer (no ztlctl command needed)
   # ztlctl does not index or mutate garden/ content
   ```

7. **How The Paradigms Map** — keep the existing 3-row table from current paradigms.md (Zettelkasten / Second-brain / Knowledge-garden). This table is accurate and should remain.

8. **What ztlctl Does Not Claim** — keep the existing 3-bullet list verbatim. It's accurate.

9. **Intended Flow** — keep the existing 4-step numbered list verbatim. Accurate.

10. **Next Steps** section (new):
    ```markdown
    ## Next Steps

    - Follow the [Tutorial](tutorial.md) to build your first vault end-to-end
    - Read [Core Concepts](concepts.md) for the full content type and maturity tier reference
    - See [Agentic Workflows](agentic-workflows.md) for session lifecycle, recipe walkthroughs, and MCP integration
    ```

**Tone rules (from tutorial.md gold standard):**
- Short explanatory sentence → code block → brief outcome note
- Use `!!! tip` admonitions for best-practice shortcuts
- Use `!!! note` for important behavioral caveats
- Each scenario is self-contained — the reader doesn't need to read other guides first
  </action>

  <verify>
    <automated>wc -l /Users/shparki/Documents/Workspace/thatdev/ztlctl/docs/paradigms.md</automated>
  </verify>

  <acceptance_criteria>
    - File is 160+ lines
    - Contains `## Second-Brain vs Knowledge Garden` heading
    - Contains "Choose Your Path" heading or section
    - Contains comparison table with "Second-Brain" and "Knowledge Garden" columns
    - Contains `agent session start` command in a code block
    - Contains `query packet --mode review` command in a code block
    - Contains `query list --maturity seed` command in a code block
    - Contains "Next Steps" section linking to tutorial.md, concepts.md, agentic-workflows.md
    - `mkdocs build --strict` passes with no errors
  </acceptance_criteria>

  <done>docs/paradigms.md is 160+ lines, contains comparison table, "choose your path" guidance, 3 concrete command-sequence scenarios, explanation that paradigms coexist, and a next-steps section. mkdocs build --strict passes.</done>
</task>

</tasks>

<verification>
After task completes:

```bash
# Verify line count
wc -l docs/paradigms.md

# Verify key content markers
grep -c "second-brain\|knowledge garden\|Choose Your Path" docs/paradigms.md

# Verify build passes
mkdocs build --strict 2>&1 | tail -5
```
</verification>

<success_criteria>
- docs/paradigms.md is 160+ lines (up from 72)
- Comparison table present with second-brain vs knowledge-garden dimensions
- "Choose your path" scenario guidance for 3 situations
- All 3 scenarios have full command sequences with annotations
- Paradigms-coexist explanation present
- Next steps links to tutorial.md, concepts.md, agentic-workflows.md
- `mkdocs build --strict` exits 0
</success_criteria>

<output>
After completion, create `.planning/phases/10-user-guide-content/10-01-SUMMARY.md`
</output>
