pan-docs · diff
v2.0.0 to v2.0.0
5 added, 5 removed. Audit A to A.
---
name: pan-docs
- description: Find, update, and structure Panopticon documentation using the docs index and documentation guide
- author: Panopticon
+ description: Find, update, and structure Overdeck documentation using the docs index and documentation guide
+ author: Overdeck
version: 2.0.0
triggers:
- panopticon docs
- find in panopticon docs
- where is documentation for
- panopticon documentation
- pan docs
- update docs
- update panopticon docs
allowed-tools:
- Read
- Grep
- Glob
- Edit
---
# Pan-Docs Skill
- **Purpose:** Be the single Panopticon-specific skill for finding, updating, and improving documentation.
+ **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 Panopticon documentation skill. If you need general prose cleanup, use `clear-writing` as a supporting skill, not as a replacement for Panopticon-specific documentation judgment.
+ 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 `docs/INDEX.md` before guessing where information lives.
- 2. **Write for the reader who is new to Panopticon.** Lead with purpose and mental model before code paths or implementation details.
+ 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 `docs/INDEX.md` too.
For the full writing philosophy and maintenance guidance, read:
- `.claude/skills/update-panopticon-docs/resources/STYLE_GUIDE.md`
- `.claude/skills/update-panopticon-docs/resources/DOC_LOCATIONS.md`
- `.claude/skills/update-panopticon-docs/resources/EXAMPLES.md`
---
## Workflow
### 1. Find the right document
Read `docs/INDEX.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 `docs/INDEX.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
- `docs/INDEX.md` still helps someone find the topic
---
## Common Uses
### Answer a docs question
1. Read `docs/INDEX.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 `docs/INDEX.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 | `docs/INDEX.md` |
| Documentation philosophy | `.claude/skills/update-panopticon-docs/resources/STYLE_GUIDE.md` |
| Where docs belong | `.claude/skills/update-panopticon-docs/resources/DOC_LOCATIONS.md` |
| Common update patterns | `.claude/skills/update-panopticon-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 `docs/INDEX.md` so the topic is findable next time