Pan-Docs Skill

Purpose: Be the single Overdeck-specific skill for finding, updating, and improving documentation.

Use this skill for three kinds of work:

• answering questions from existing docs
• deciding where new documentation should live
• updating docs so they stay newcomer-friendly, consistent, and discoverable

This is the primary Overdeck documentation skill. If you need general prose cleanup, use clear-writing as a supporting skill, not as a replacement for Overdeck-specific documentation judgment.

---

Core Rules

1. Start with the docs index. Use the Topic Index in CLAUDE.md before guessing where information lives.
2. Write for the reader who is new to Overdeck. Lead with purpose and mental model before code paths or implementation details.
3. One document should do one job well. Keep overview docs, routing references, workflow guides, and implementation deep dives distinct.
4. Prefer linking over duplicating. If another doc already owns the detail, summarize briefly and point there.
5. Keep the index current. If docs coverage changes, update the Topic Index in CLAUDE.md too.

For the full writing philosophy and maintenance guidance, read:

• .claude/skills/update-overdeck-docs/resources/STYLE_GUIDE.md
• .claude/skills/update-overdeck-docs/resources/DOC_LOCATIONS.md
• .claude/skills/update-overdeck-docs/resources/EXAMPLES.md

---

Workflow

1. Find the right document

Read the Topic Index in CLAUDE.md first.

Use:

• category tables to find the owning document
• Topic Quick-Find to find likely matches by keyword

If the index is not enough, grep the docs tree.

2. Decide the document type before editing

Ask what kind of document this is:

• Overview doc — newcomer mental model first
• Reference doc — lookup table or canonical options
• Workflow doc — how stages interact over time
• Implementation deep dive — internals and code-shaped detail

Do not mix these levels unless the file already clearly does one job.

3. Update the target document

When editing:

• preserve the file's existing role
• up-level docs that drift into code-audit detail when they are meant to orient newcomers
• keep terminology consistent with neighboring docs
• add links to related docs instead of repeating their full content

4. Update the index

Whenever documentation coverage changes:

• add new files to the Topic Index in CLAUDE.md
• update descriptions if a file's role changed
• add or adjust Topic Quick-Find keywords when new topic coverage appears

5. Verify the docs surface

After editing, check:

• the file still matches its intended audience and abstraction level
• links point to the right owner docs
• the Topic Index in CLAUDE.md still helps someone find the topic

---

Common Uses

Answer a docs question

1. Read the Topic Index in CLAUDE.md
2. Read the identified file(s)
3. Answer with file references

Add or update documentation

1. Identify the owning document type
2. Read the full file before editing
3. Keep the explanation at the right level for that doc
4. Update the Topic Index in CLAUDE.md if discoverability changed

Clean up confusing docs

When a doc feels too low-level for its audience:

• keep exact implementation details in the deeper doc
• rewrite the overview to explain what exists, when it appears, and why it matters
• add links to the deeper reference instead of embedding the full internals

---

Quick Pointers

Need	Start here
Find documentation	the Topic Index in CLAUDE.md
Documentation philosophy	.claude/skills/update-overdeck-docs/resources/STYLE_GUIDE.md
Where docs belong	.claude/skills/update-overdeck-docs/resources/DOC_LOCATIONS.md
Common update patterns	.claude/skills/update-overdeck-docs/resources/EXAMPLES.md
General prose cleanup	clear-writing

---

When docs are missing

If the index and docs search do not reveal coverage:

1. confirm the topic is really missing
2. choose the smallest correct owning doc
3. add the documentation there
4. update the Topic Index in CLAUDE.md so the topic is findable next time