Documentation planner
Find the gaps in the user guide and the design guide, and produce a backlog in priority order.
Inputs
- Scope: all docs, one guide, or one area. The default is all docs.
- Signals (optional): issues, questions from operators, or review findings.
Process
Step 1: Inventory
List each page in docs/user/ and docs/design/, and each crate README.md that serves a
consumer. For each page, record its guide, its content type, and its area. Also read:
docs/README.md and the README.md of each guide, for the stated structure.
- The "still to come" list in
docs/design/README.md, for the planned design pages.
Step 2: Find the gaps
Compare the inventory with each of these:
- The product surface. Each CLI verb, each
box.toml top-level key, each process
specification key, each filesystem list, the policy action vocabulary, and each binary that
ships. A part of the surface with no page is a gap.
- The content types. For each area, the user guide needs a how-to and a reference, and the
design guide needs an explanation. An area with a reference and no how-to has a gap.
- The premises in
AGENTS.md. Each premise needs a design page that explains it to a security
evaluator. A premise that only AGENTS.md explains is a gap.
- Signals. If
gh is available, read the open issues in the repository that mention docs. Map
each to a page that is unclear or to a page that is missing.
Step 3: Prioritize
- P0, do now. High impact, at any effort. Getting started, the architecture overview, and the
security model.
- P1, do soon. Medium impact, low effort. A how-to for a common task, or a reference for a
surface that has none.
- P2, plan for. Medium impact, high effort. An enforcement page, or the platform differences.
- P3, backlog. Low impact. An edge case.
Step 4: Write the backlog
## Docs backlog: <scope>
**Date:** <date>
**Pages inventoried:** <count>
**Gaps found:** <count>
### P0: do now
- [ ] <Task>: <content type>, <target path>. <Reason.>
### P1: do soon
...
### Coverage
| Area | Tutorial | How-to | Reference | Explanation |
|---|---|---|---|---|
| Running a harness | Y | ~ | N | N |
| Filesystem grants | N | N | ~ | N |
| Binaries | N | N | N | N |
### From signals
- <A theme from the signals, and the gap that it maps to.>
Y is covered, ~ is partial, and N is missing.
What this skill does not do
- Write a page. That is
docs-writer.
- Create issues or tasks in an external tool.
1---2name: docs-planner-23description: Find the gaps in the Box documentation and produce a prioritized backlog for docs/user/ and docs/design/. Use when planning documentation work, after a feature or a binary ships without a page, for a periodic health check of the docs, or when asked "what docs need writing", "plan the docs work", "prioritize the docs backlog", or "what should we document next".4metadata:5 source: https://skillmd.com/skills/strands-agents/docs-planner-26---78# Documentation planner910Find the gaps in the user guide and the design guide, and produce a backlog in priority order.1112## Inputs1314- **Scope**: all docs, one guide, or one area. The default is all docs.15- **Signals** (optional): issues, questions from operators, or review findings.1617## Process1819### Step 1: Inventory2021List each page in `docs/user/` and `docs/design/`, and each crate `README.md` that serves a22consumer. For each page, record its guide, its content type, and its area. Also read:2324- `docs/README.md` and the `README.md` of each guide, for the stated structure.25- The "still to come" list in `docs/design/README.md`, for the planned design pages.2627### Step 2: Find the gaps2829Compare the inventory with each of these:3031- **The product surface.** Each CLI verb, each `box.toml` top-level key, each process32 specification key, each filesystem list, the policy action vocabulary, and each binary that33 ships. A part of the surface with no page is a gap.34- **The content types.** For each area, the user guide needs a how-to and a reference, and the35 design guide needs an explanation. An area with a reference and no how-to has a gap.36- **The premises in `AGENTS.md`.** Each premise needs a design page that explains it to a security37 evaluator. A premise that only `AGENTS.md` explains is a gap.38- **Signals.** If `gh` is available, read the open issues in the repository that mention docs. Map39 each to a page that is unclear or to a page that is missing.4041### Step 3: Prioritize4243- **P0, do now.** High impact, at any effort. Getting started, the architecture overview, and the44 security model.45- **P1, do soon.** Medium impact, low effort. A how-to for a common task, or a reference for a46 surface that has none.47- **P2, plan for.** Medium impact, high effort. An enforcement page, or the platform differences.48- **P3, backlog.** Low impact. An edge case.4950### Step 4: Write the backlog5152```markdown53## Docs backlog: <scope>5455**Date:** <date>56**Pages inventoried:** <count>57**Gaps found:** <count>5859### P0: do now6061- [ ] <Task>: <content type>, <target path>. <Reason.>6263### P1: do soon6465...6667### Coverage6869| Area | Tutorial | How-to | Reference | Explanation |70|---|---|---|---|---|71| Running a harness | Y | ~ | N | N |72| Filesystem grants | N | N | ~ | N |73| Binaries | N | N | N | N |7475### From signals7677- <A theme from the signals, and the gap that it maps to.>78```7980`Y` is covered, `~` is partial, and `N` is missing.8182## What this skill does not do8384- Write a page. That is `docs-writer`.85- Create issues or tasks in an external tool.