@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/design-theme/themes/tsumagoi-ranch.md

@@ -0,0 +1,150 @@
+# Tsumagoi Ranch Theme
+
+Neo-Brutalist "Cute-alism" theme inspired by Japanese ranch and campground aesthetics.
+
+## Design Philosophy
+- Bold 3px borders with hard-edge offset shadows (no blur)
+- High contrast dark borders on light backgrounds
+- Playful yet professional - "Neo-Brutalism meets cute"
+- Nature-inspired color palette with mountain, forest, and campfire tones
+
+## Color Palette
+
+### Light Mode
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| **Primary** | `#0c85f4` | Mountain blue - primary actions, links |
+| **Secondary** | `#10b981` | Pine green - success, online status |
+| **Accent** | `#ff6b35` | Campfire orange - energetic CTAs |
+| **Accent Alt** | `#FF6D38` | Navigate orange - primary CTA buttons |
+| **Premium** | `#8584FF` | Navigate purple - creative accents |
+| **Warning** | `#f59e0b` | Warm amber - alerts, temperature |
+| **Danger** | `#ef4444` | Error red |
+| **Background Page** | `#faf7f2` | Warm cream |
+| **Background Card** | `#ffffff` | Pure white |
+| **Border Default** | `#d4c4a8` | Sand/wood tone |
+| **Border Strong** | `#b8a080` | Darker sand |
+| **Text Primary** | `#1a1a1a` | Near black |
+| **Text Secondary** | `#4a4a4a` | Dark gray |
+| **Text Muted** | `#6b6b6b` | Medium gray |
+| **Shadow Color** | `#b8a080` | Wood tone shadow |
+
+### Dark Mode (Night Sky)
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| **Background Page** | `#0c1424` | Night sky deep |
+| **Background Card** | `#162b47` | Night blue |
+| **Border Default** | `#3d699a` | Night blue border |
+| **Text Primary** | `#ffffff` | Pure white |
+| **Text Secondary** | `#f1f5f9` | Bright off-white |
+| **Text Muted** | `#cbd5e1` | Light gray |
+| **Shadow Color** | `#1e4a72` | Night shadow |
+
+## Typography
+
+| Element | Font | Fallback | Weight |
+|---------|------|----------|--------|
+| **Headings** | M PLUS Rounded 1c | system-ui, sans-serif | 700-900 |
+| **Body EN** | Inter | system-ui, sans-serif | 400-600 |
+| **Body JP** | Noto Sans JP | sans-serif | 400-600 |
+| **Data/Numbers** | JetBrains Mono | monospace | 700-900 |
+| **Pixel/Retro** | VT323 | monospace | 400 |
+
+## Neo-Brutal Shadow System
+
+```css
+--shadow-sm: 2px 2px 0 0 var(--shadow-color);   /* Badges, Tooltips */
+--shadow-md: 3px 3px 0 0 var(--shadow-color);   /* Buttons, Popovers */
+--shadow-lg: 4px 4px 0 0 var(--shadow-color);   /* Cards */
+--shadow-xl: 5px 5px 0 0 var(--shadow-color);   /* Hover emphasis */
+```
+
+## Border Configuration
+
+| Element | Width | Radius |
+|---------|-------|--------|
+| Badges (static) | 1px | rounded-full |
+| Chips (interactive) | 2px | rounded-full |
+| Buttons | 3px | rounded-lg (8px) |
+| Cards | 3px | rounded-xl (16px) |
+| Inputs | 2px | rounded-lg (8px) |
+
+## Motion Tokens
+
+```css
+--motion-duration-fast: 100ms;
+--motion-duration-normal: 150ms;
+--motion-duration-slow: 300ms;
+--motion-ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
+--motion-ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+## Cute-alism Accent Colors
+
+| Color | Hex | Usage |
+|-------|-----|-------|
+| Campfire | `#ff6b35` | Warm, energetic, action |
+| Twilight | `#a855f7` | Magical, dreamy, premium |
+| Sakura | `#ec4899` | Soft, friendly, approachable |
+| Moss | `#84cc16` | Earthy, grounded, organic |
+
+## Retro Pixel Palette (8-bit)
+
+| Color | Hex | Usage |
+|-------|-----|-------|
+| Cyan | `#00FFFF` | CRT cyan |
+| Magenta | `#FF00FF` | Neon magenta |
+| Lime | `#00FF66` | Pixel green |
+| Yellow | `#FFFF00` | Bright yellow |
+| Red | `#FF3366` | VHS red |
+| Blue | `#3366FF` | Deep blue |
+
+## Mobile Responsive Guidelines
+
+### Touch Targets
+- Minimum 44px (WCAG requirement)
+- Comfortable: 48px
+- Large CTAs: 56px
+
+### Spacing Scale (Mobile-First)
+```css
+--mobile-space-1: 4px;
+--mobile-space-2: 8px;
+--mobile-space-3: 12px;
+--mobile-space-4: 16px;
+```
+
+### Breakpoints
+| Name | Width | Variant |
+|------|-------|---------|
+| xs | < 640px | mobile |
+| sm | 640px | tablet |
+| md | 768px | tablet |
+| lg | 1024px | desktop |
+| xl | 1280px | desktop |
+
+### Mobile Patterns
+- Use `HorizontalScroll` for overflow content
+- Bottom sheet modals instead of center modals
+- Thumb-zone optimization (primary actions in bottom 40%)
+- Safe area padding for notched devices
+
+## Glassmorphism Presets
+
+```css
+.glass-light { background: rgba(255, 255, 255, 0.4); backdrop-filter: blur(2px); }
+.glass-medium { background: rgba(255, 255, 255, 0.55); backdrop-filter: blur(4px); }
+.glass-heavy { background: rgba(255, 255, 255, 0.75); backdrop-filter: blur(8px); }
+```
+
+## Application Guide
+
+When applying this theme:
+1. Use CSS variables from design-tokens.css
+2. Apply neo-brutal shadows with border-color-matched shadow-color
+3. Use bounce easing for interactive elements
+4. Apply stagger animations for card grids
+5. Ensure all interactive elements have 44px minimum touch targets
+6. Use glassmorphism for overlays on 3D backgrounds

package/skills/docs-adr/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: docs-adr
+description: >
+  Create and maintain lightweight Architecture Decision Records as
+  agent-readable decision memory: what was decided, why, and what was
+  rejected. Use when "record this decision", "set up ADRs", or "the agent
+  keeps suggesting Y again".
+license: MIT
+effort: high
+---
+
+# docs-adr — Decision memory the next session can load
+
+**Degree of freedom: MIXED — T1 is the priority.** What to record
+`[HIGH freedom]`; format, supersede-not-edit, and present-backfill-first
+`[LOW freedom — run exactly]`.
+
+Install and maintain the repo's decision memory. **Code shows what was
+decided; nothing shows why, or what was rejected — so every new agent
+session is free to "improve" its way back to an alternative you already
+ruled out.** Re-litigated decisions are the slowest form of drift. An
+ADR makes the decision durable and its reversal deliberate.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **docs-adr** (this) | Why we chose X; rejected alternatives; INDEX.md |
+| `plan-docs-sync` | Docs vs *what the code is* — not why |
+| `handoff` | Session state for the next chat — not permanent decisions |
+| `docs-writer` | Tutorials / README prose |
+| `enhance-arch-boundaries` | Mechanical layering; this records the model |
+| `workflow-housekeep` | Periodic index / status sweep |
+| `housekeep-backlog` | Parked-work register (`BACKLOG.md`), not decisions |
+
+## How to reason
+
+1. **Observe** — the decision, the rejected alternative, who already tried to reverse it
+2. **Interpret** — would a fresh agent "improve" back to the rejected option?
+3. **Classify** — ADR / not-an-ADR (linter already enforces, routine impl)
+4. **Severity** — load-bearing unusual choice first
+
+## Worked example
+
+> **Observe:** agent PR re-proposes Zustand; repo uses React context for
+> session by choice; no ADR.
+> **Interpret:** the rejection is oral memory — the next session will retry.
+> **Classify:** ADR — stack choice with a rejected alternative.
+> **Write:** "We use React context for session. Rejected Zustand: duplicate
+> store vs server session." Present the backfill list **before** writing files.
+
+---
+
+## Phase 0 — Set up the system (once per repo)  [LOW freedom — INDEX.md + statuses]
+
+- `docs/adr/NNNN-short-title.md`, numbered sequentially, plus
+  `docs/adr/INDEX.md` — one line per ADR
+  (`NNNN | title | status | one-line decision`). The index is the
+  agent-facing surface: small enough to load every session.
+- Reference the index from agent rules: *"Before proposing a change to
+  architecture, dependencies, conventions, or data models, read
+  `docs/adr/INDEX.md`; do not contradict an Accepted ADR without flagging
+  it explicitly to the user."*
+- Statuses: **Proposed → Accepted → Superseded by NNNN / Deprecated**.
+  Never edit an Accepted ADR's decision — supersede it with a new one
+  that links back. History is the point.
+
+---
+
+## Phase 1 — The format (one page, hard cap)  [LOW freedom — this shape]
+
+```
+# NNNN. <Decision as a verb phrase>
+Status: Accepted            Date: YYYY-MM-DD
+## Context
+2–5 sentences: the forces. What problem, what constraints.
+## Decision
+1–3 sentences, imperative: "We use X for Y."
+## Rejected alternatives
+The load-bearing section for agents. Each alternative: one line — what
+it was, WHY it lost. This is what stops re-proposal.
+## Consequences
+2–4 sentences: what this commits us to, what it makes harder, when to
+revisit.
+```
+
+No restating documentation, no tutorials, no aspirational essays. If it
+exceeds a page it is two decisions or it is documentation (route to
+`docs-writer`). "We tried it and it failed because…" is the highest-value
+content — failure memory is exactly what a fresh session lacks.
+
+---
+
+## Phase 2 — What gets an ADR (and what does not)  [HIGH freedom]
+
+Write one for any decision an agent could plausibly reverse while
+"helping":
+
+- Stack and dependency choices (and the ones rejected), including
+  versions pinned for a reason.
+- Architecture and layering (`enhance-arch-boundaries` model is ADR #1
+  material).
+- Conventions with non-obvious rationale.
+- Product / scope decisions that shape code ("no user accounts in v1 —
+  deliberately").
+- Reversals of past attempts — the "we already tried that" archive.
+
+**Not** ADRs: routine implementation choices, anything the linter / gate
+already enforces mechanically, TODOs, meeting notes. Over-recording kills
+the system as surely as under-recording.
+
+---
+
+## Phase 3 — Backfill mode (existing repo)  [LOW freedom — confirm list before writing]
+
+Mine implicit decisions before they are lost:
+
+- From the code: unusual choices that look wrong but are load-bearing
+  (the thing every new agent "fixes" first).
+- From git history / PR descriptions: reversions and migrations.
+- From the user, one focused pass: "What has an agent (or a past you)
+  tried to change that must stay, and why?" Write those first.
+
+Cap the backfill at decisions that still bind (typically 5–15). This is
+memory, not archaeology for its own sake.
+
+---
+
+## Phase 4 — Keep it alive  [LOW freedom — supersede, do not edit Accepted]
+
+- New ADR in the same PR as the decision it records.
+- `/handoff` / completion: any decision that meets the Phase-2 bar gets
+  filed before closure (`enhance-agent-guardrails` can install the
+  reminder).
+- When an agent's proposal contradicts an Accepted ADR: **surface, cite,
+  ask** — do not silently comply *or* silently override. Changing course
+  produces a superseding ADR, on purpose, by the human.
+- Periodic sweep (fits `workflow-housekeep`): statuses current, index
+  matches files, superseded chains intact.
+
+---
+
+## Definition of Done
+
+- [ ] `docs/adr/` + INDEX.md exist; numbering and statuses in place
+- [ ] Agent rules load the index each session and forbid silent contradiction of Accepted ADRs
+- [ ] Format enforced: one page, rejected-alternatives section present, supersede-not-edit
+- [ ] Scope rules recorded (what does / does not get an ADR)
+- [ ] Backfill done for still-binding decisions, "things agents keep trying to change" first
+- [ ] Same-PR rule and handoff hook wired
+- [ ] Index verified against files (no dangling numbers, no unindexed ADRs)
+
+## Self-critique before writing ADRs  [LOW freedom — do not skip]
+
+1. **Backfill list shown first** — decisions are theirs; recording is yours
+2. **Rejected alternatives filled** — an ADR without them will not stop re-proposal
+3. **One page** — two decisions or it's docs (`docs-writer`)
+4. **Never edit Accepted** — supersede
+5. **Not everything** — linter-enforced and TODOs stay out
+
+## Output format
+
+1. **System files** — the directory, INDEX.md, agent-rule text added
+2. **Backfilled ADRs** — each one page, rejected-alternatives filled
+3. **Lifecycle wiring** — same-PR rule, handoff hook, housekeep sweep item
+
+Present the backfill list for confirmation **before** writing the ADRs —
+the decisions are theirs; the recording is yours.

package/skills/docs-coauthor/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: docs-coauthor
+description: >
+  Co-author structured documents (specs, PRDs, RFCs, proposals) in three
+  stages: gather context, draft, reader-test. Use when writing a proposal,
+  technical spec, or similar long-form document. Decision records → docs-adr.
+license: MIT
+---
+
+# Doc Co-Authoring Workflow
+
+**Degree of freedom: MIXED.** What to ask and what to keep `[HIGH freedom]`;
+the three-stage order, six-step section loop, and Reader Testing
+`[LOW freedom — run exactly]`.
+
+ a structured workflow for guiding users through collaborative document creation. Act as an active guide, walking users through three stages: Context Gathering, Refinement & Structure, and Reader Testing.
+
+> **Guiding principle — orient the reader before the mechanism.** Even a spec, PRD, or RFC should *open* by answering what this is, why it exists, and who it's for — in plain language — before diving into detail. That's the same reader-first instinct this workflow's Reader Testing stage enforces at the end; apply it from the first sentence. See `docs-writer` for the full "write for the reader's mental model first" rule.
+
+## How to reason
+
+1. **Observe** — doc type, audience, desired impact, template or existing draft
+2. **Interpret** — what the next reader will lack that the authors already know
+3. **Classify** — offer the workflow / work freeform / start at the highest-unknown section
+4. **Test** — predict reader questions; a fresh instance must answer them from the doc alone
+
+## Worked example
+
+> **Observe:** "write a PRD for billing v2"; no audience named; a Slack thread already rejected a usage-only model.
+> **Interpret:** that rejection is oral — a pasted PRD will fail when a reader (or a fresh agent) lacks it.
+> **Classify:** offer the three stages; Context Gathering first (eng + finance; impact = stop re-arguing usage-only).
+> **Do not** draft the PRD in the first reply.
+
+## Self-critique before reporting
+
+- **Reader-first open** — what / why / who before mechanism
+- **Fresh-instance test ran** — an author reread is not Reader Testing
+- **User owns the doc** — they confirm impact; you do not ship unreviewed
+- **Right owner** — INDEX.md / rejected alternatives → `docs-adr`; README prose → `docs-writer`
+
+## When to Offer This Workflow  [HIGH freedom]
+
+**Trigger conditions:**
+- User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
+- User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
+- User seems to be starting a substantial writing task
+
+**Initial offer:**
+Offer the user a structured workflow for co-authoring the document. Explain the three stages:
+
+1. **Context Gathering**: User provides all relevant context while Claude asks clarifying questions
+2. **Refinement & Structure**: Iteratively build each section through brainstorming and editing
+3. **Reader Testing**: Test the doc with a fresh Claude (no context) to catch blind spots before others read it
+
+Explain that this approach helps ensure the doc works well when others read it (including when they paste it into Claude). Ask if they want to try this workflow or prefer to work freeform.
+
+If user declines, work freeform. If user accepts, proceed to Stage 1.
+
+## Stage 1: Context Gathering  [HIGH freedom]
+
+**Goal:** Close the gap between what the user knows and what Claude knows, enabling smart guidance later.
+
+### Initial Questions
+
+Start by asking the user for meta-context about the document:
+
+1. What type of document is this? (e.g., technical spec, decision doc, proposal)
+2. Who's the primary audience?
+3. What's the desired impact when someone reads this?
+4. Is there a template or specific format to follow?
+5. Any other constraints or context to know?
+
+Inform them they can answer in shorthand or dump information however works best for them.
+
+**If user provides a template or mentions a doc type:**
+- Ask if they have a template document to share
+- If they provide a link to a shared document, use the appropriate integration to fetch it
+- If they provide a file, read it
+
+**If user mentions editing an existing shared document:**
+- Use the appropriate integration to read the current state
+- Check for images without alt-text
+- If images exist without alt-text, explain that when others use Claude to understand the doc, Claude won't be able to see them. Ask if they want alt-text generated. If so, request they paste each image into chat for descriptive alt-text generation.
+
+### Info Dumping
+
+Once initial questions are answered, encourage the user to dump all the context they have. Request information such as:
+- Background on the project/problem
+- Related team discussions or shared documents
+- Why alternative solutions aren't being used
+- Organizational context (team dynamics, past incidents, politics)
+- Timeline pressures or constraints
+- Technical architecture or dependencies
+- Stakeholder concerns
+
+Advise them not to worry about organizing it - just get it all out. Offer multiple ways to provide context:
+- Info dump stream-of-consciousness
+- Point to team channels or threads to read
+- Link to shared documents
+
+**If integrations are available** (e.g., Slack, Teams, Google Drive, SharePoint, or other MCP servers), mention that these can be used to pull in context directly.
+
+**If no integrations are detected and in Claude.ai or Claude app:** Suggest they can enable connectors in their Claude settings to allow pulling context from messaging apps and document storage directly.
+
+Inform them clarifying questions will be asked once they've done their initial dump.
+
+**During context gathering:**
+
+- If user mentions team channels or shared documents:
+ - If integrations available: Inform them the content will be read now, then use the appropriate integration
+ - If integrations not available: Explain lack of access. Suggest they enable connectors in Claude settings, or paste the relevant content directly.
+
+- If user mentions entities/projects that are unknown:
+ - Ask if connected tools should be searched to learn more
+ - Wait for user confirmation before searching
+
+- As user provides context, track what's being learned and what's still unclear
+
+**Asking clarifying questions:**
+
+When user signals they've done their initial dump (or after substantial context provided), ask clarifying questions to ensure understanding:
+
+Generate 5-10 numbered questions based on gaps in the context.
+
+Inform them they can use shorthand to answer (e.g., "1: yes, 2: see #channel, 3: no because backwards compat"), link to more docs, point to channels to read, or just keep info-dumping. Whatever's most efficient for them.
+
+**Exit condition:**
+Sufficient context has been gathered when questions show understanding - when edge cases and trade-offs can be asked about without needing basics explained.
+
+**Transition:**
+Ask if there's any more context they want to provide at this stage, or if it's time to move on to drafting the document.
+
+If user wants to add more, let them. When ready, proceed to Stage 2.
+
+## Stage 2: Refinement & Structure  [LOW freedom — run the six steps]
+
+**Goal:** Build the document section by section through brainstorming, curation, and iterative refinement.
+
+**Instructions to user:**
+Explain that the document will be built section by section. For each section:
+1. Clarifying questions will be asked about what to include
+2. 5-20 options will be brainstormed
+3. User will indicate what to keep/remove/combine
+4. The section will be drafted
+5. It will be refined through surgical edits
+
+Start with whichever section has the most unknowns (usually the core decision/proposal), then work through the rest.
+
+**Section ordering:**
+
+If the document structure is clear:
+Ask which section they'd like to start with.
+
+Suggest starting with whichever section has the most unknowns. For decision docs, that's usually the core proposal. For specs, it's typically the technical approach. Summary sections are best left for last.
+
+If user doesn't know what sections they need:
+Based on the type of document and template, suggest 3-5 sections appropriate for the doc type.
+
+Ask if this structure works, or if they want to adjust it.
+
+**Once structure is agreed:**
+
+Create the initial document structure with placeholder text for all sections.
+
+**For each section:**
+
+### Step 1: Clarifying Questions
+
+Announce work will begin on the [SECTION NAME] section. Ask 5-10 clarifying questions about what should be included:
+
+Generate 5-10 specific questions based on context and section purpose.
+
+Inform them they can answer in shorthand or just indicate what's important to cover.
+
+### Step 2: Brainstorming
+
+For the [SECTION NAME] section, brainstorm [5-20] things that might be included, depending on the section's complexity. Look for:
+- Context shared that might have been forgotten
+- Angles or considerations not yet mentioned
+
+Generate 5-20 numbered options based on section complexity. At the end, offer to brainstorm more if they want additional options.
+
+### Step 3: Curation
+
+Ask which points should be kept, removed, or combined. Request brief justifications to help learn priorities for the next sections.
+
+Provide examples:
+- "Keep 1,4,7,9"
+- "Remove 3 (duplicates 1)"
+- "Remove 6 (audience already knows this)"
+- "Combine 11 and 12"
+
+**If user gives freeform feedback** (e.g., "looks good" or "I like most of it but...") instead of numbered selections, extract their preferences and proceed. Parse what they want kept/removed/changed and apply it.
+
+### Step 4: Gap Check
+
+Based on what they've selected, ask if there's anything important missing for the [SECTION NAME] section.
+
+### Step 5: Drafting
+
+Replace only this section's placeholder with the drafted content — an in-place edit, never a reprint of the whole document.
+
+Announce the [SECTION NAME] section will be drafted now based on what they've selected.
+
+Ask them to read through it and indicate what to change. Note that being specific helps learning for the next sections.
+
+**Key instruction for user (include when drafting the first section):**
+Provide a note: Instead of editing the doc directly, ask them to indicate what to change. This helps learning of their style for future sections. For example: "Remove the X bullet - already covered by Y" or "Make the third paragraph more concise".
+
+### Step 6: Iterative Refinement
+
+As user provides feedback:
+- Edit in place, surgically — never reprint the whole doc
+- If user edits doc directly and asks to read it: mentally note the changes they made and keep them in mind for future sections (this shows their preferences)
+
+**Continue iterating** until user is satisfied with the section.
+
+### Quality Checking
+
+When iterations stop producing substantial changes, ask if anything can be removed without losing important information.
+
+When section is done, confirm [SECTION NAME] is complete. Ask if ready to move to the next section.
+
+**Repeat for all sections.**
+
+### Near Completion
+
+As approaching completion (80%+ of sections done), announce intention to re-read the entire document and check for:
+- Flow and consistency across sections
+- Redundancy or contradictions
+- Mannered prose — sentences that perform writing instead of saying something: throat-clearing openers, stacked hedges, "it's worth noting", triplets for rhythm, a closing line that restates the paragraph. One plain sentence per idea; a list or table where the content is multifaceted, prose where it is one idea
+- Whether every sentence carries weight
+
+Read entire document and provide feedback.
+
+**When all sections are drafted and refined:**
+Announce all sections are drafted. Indicate intention to review the complete document one more time.
+
+Review for overall coherence, flow, completeness.
+
+Provide any final suggestions.
+
+Ask if ready to move to Reader Testing, or if they want to refine anything else.
+
+## Stage 3: Reader Testing  [LOW freedom — run exactly]
+
+**Goal:** Test the document with a fresh Claude (no context bleed) to verify it works for readers.
+
+**Instructions to user:**
+Explain that testing will now occur to see if the document actually works for readers. This catches blind spots - things that make sense to the authors but might confuse others.
+
+### Testing Approach
+
+**If access to sub-agents is available (e.g., in Claude Code):**
+
+Perform the testing directly without user involvement.
+
+### Step 1: Predict Reader Questions
+
+Announce intention to predict what questions readers might ask when trying to discover this document.
+
+Generate 5-10 questions that readers would realistically ask.
+
+### Step 2: Test with Sub-Agent
+
+Announce that these questions will be tested with a fresh Claude instance (no context from this conversation).
+
+For each question, invoke a sub-agent with just the document content and the question. The questions are independent — launch all the sub-agents in one message so they run in parallel, and brief each once, precisely.
+
+Summarize what Reader Claude got right/wrong for each question.
+
+### Step 3: Run Additional Checks
+
+Announce additional checks will be performed.
+
+Invoke sub-agent to check for ambiguity, false assumptions, contradictions.
+
+Summarize any issues found.
+
+### Step 4: Report and Fix
+
+If issues found:
+Report that Reader Claude struggled with specific issues.
+
+List the specific issues.
+
+Indicate intention to fix these gaps.
+
+Loop back to refinement for problematic sections.
+
+---
+
+**If no access to sub-agents (e.g., claude.ai web interface):**
+
+The user will need to do the testing manually.
+
+### Step 1: Predict Reader Questions with the User
+
+Ask what questions people might ask when trying to discover this document. What would they type into Claude.ai?
+
+Generate 5-10 questions that readers would realistically ask.
+
+### Step 2: Setup Testing
+
+Provide testing instructions:
+1. Open a fresh Claude conversation: https://claude.ai
+2. Paste or share the document content (if using a shared doc platform with connectors enabled, provide the link)
+3. Ask Reader Claude the generated questions
+
+For each question, instruct Reader Claude to provide:
+- The answer
+- Whether anything was ambiguous or unclear
+- What knowledge/context the doc assumes is already known
+
+Check if Reader Claude gives correct answers or misinterprets anything.
+
+### Step 3: Additional Checks
+
+Also ask Reader Claude:
+- "What in this doc might be ambiguous or unclear to readers?"
+- "What knowledge or context does this doc assume readers already have?"
+- "Are there any internal contradictions or inconsistencies?"
+
+### Step 4: Iterate Based on Results
+
+Ask what Reader Claude got wrong or struggled with. Indicate intention to fix those gaps.
+
+Loop back to refinement for any problematic sections.
+
+---
+
+### Exit Condition (Both Approaches)
+
+When Reader Claude consistently answers questions correctly and doesn't surface new gaps or ambiguities, the doc is ready.
+
+## Final Review  [LOW freedom — do not skip]
+
+When Reader Testing passes:
+Announce the doc has passed Reader Claude testing. Before completion:
+
+1. Recommend they do a final read-through themselves - they own this document and are responsible for its quality
+2. Suggest double-checking any facts, links, or technical details
+3. Ask them to verify it achieves the impact they wanted
+
+Ask if they want one more review, or if the work is done.
+
+**If user wants final review, provide it. Otherwise:**
+Announce document completion. Provide a few final tips:
+- Consider linking this conversation in an appendix so readers can see how the doc was developed
+- Use appendices to provide depth without bloating the main doc
+- Update the doc as feedback is received from real readers
+
+## Tips for Effective Guidance
+
+**Tone:**
+- Be direct and procedural
+- Explain rationale briefly when it affects user behavior
+- Don't try to "sell" the approach - just execute it
+
+**Handling Deviations:**
+- If user wants to skip a stage: Ask if they want to skip this and write freeform
+- If user seems frustrated: Acknowledge this is taking longer than expected. Suggest ways to move faster
+- Always give user agency to adjust the process
+
+**Context Management:**
+- Throughout, if context is missing on something mentioned, proactively ask
+- Don't let gaps accumulate - address them as they come up
+