docs: trim live roadmap and guidance
This commit is contained in:
+40
-80
@@ -1,99 +1,59 @@
|
|||||||
# docs management
|
# Documentation workflow
|
||||||
|
|
||||||
its the age old problem. code changes, but i dont bother fixing docs. its been here before me, before chatgpt, and after chatgpt.
|
Keep live documentation authoritative and short. Use
|
||||||
|
[`README.md`](README.md) as the index for current documentation.
|
||||||
|
|
||||||
## lets improve this
|
## Before editing documentation
|
||||||
|
|
||||||
check [README.md](README.md) as pointers. they point to live evolving docs.
|
- Read the nearby live document and [`current_roadmap.md`](current_roadmap.md).
|
||||||
|
- Search for the concept and any filenames you plan to change.
|
||||||
|
- Preserve unrelated user changes in the worktree.
|
||||||
|
|
||||||
a good docs pass, searching for kw, changing the documents that have them. cool. dedicated docs pass after a Thing done. great.
|
## Separate live and historical documents
|
||||||
|
|
||||||
ACTIVE (planned, running) implementation plans and specs sit in their folders.
|
Use these locations consistently:
|
||||||
`superpowers/plans/` is only for executable handoff plans that are active or in
|
|
||||||
progress.
|
|
||||||
|
|
||||||
DONE docs go straight to [`historical/`](historical/). Prefer keeping the OG
|
- `superpowers/plans/` contains active executable implementation plans.
|
||||||
path shape under `docs/historical/`, for example
|
- `superpowers/specs/` contains current design contracts.
|
||||||
`docs/superpowers/plans/foo.md` -> `docs/historical/superpowers/plans/foo.md`.
|
- `historical/` contains completed plans, superseded designs, and narrative
|
||||||
You can edit the top of the file to state that its historical, but just being
|
history. Preserve the original path below `historical/` when practical.
|
||||||
in the folder is enough.
|
|
||||||
|
|
||||||
superpowers skills say to tick those boxes; do tick those boxes.
|
When work finishes, check every box in its implementation plan and move the
|
||||||
|
plan to `historical/`. Update live links after moving or retiring a document.
|
||||||
|
Search at least `README.md`, `current_roadmap.md`, `../skills/`, and nearby
|
||||||
|
architecture documents.
|
||||||
|
|
||||||
stale docs, even at docs/, go to historical/ or git rm.
|
Update a specification in place while it remains the current contract. Move it
|
||||||
|
to `historical/` when it only explains how the code reached its current shape.
|
||||||
|
Keep one source of truth for current behavior.
|
||||||
|
|
||||||
user facing docs need updates too. User facing docs include [/skills](../skills/)
|
## Keep the roadmap live
|
||||||
|
|
||||||
## roadmap plans?
|
Limit `current_roadmap.md` to the current product shape, active work, next
|
||||||
|
priorities, durable constraints, and pointers to historical detail. Move
|
||||||
|
completed narratives out of the roadmap. If it exceeds 300 lines, trim it
|
||||||
|
before adding another section.
|
||||||
|
|
||||||
in superpowers plans there are now suddenly some big plans, like roadmaps, with multiple slices that turn into dedicated implementation plans.
|
## Keep code and documentation consistent
|
||||||
|
|
||||||
Those need linking, active or done. Since any done plans go to `historical/**`,
|
Update user-facing documentation and repository skills when behavior changes.
|
||||||
live docs must point to `historical/**` when they cite old slice plans.
|
If a live document describes a partial implementation, add a short comment or
|
||||||
|
docstring at the code seam. Future agents usually encounter code first.
|
||||||
|
|
||||||
`current_roadmap.md` is the live roadmap. Roadmap-shaped plan files are
|
## Verify Markdown edits
|
||||||
historical context unless they are actively being used to drive this exact next
|
|
||||||
slice.
|
|
||||||
|
|
||||||
## superpowers specs? (generalize to docs/)
|
Run Markdown lint on the exact files you changed:
|
||||||
|
|
||||||
Any specs files in that folder represent the current state of the code. Ok
|
```powershell
|
||||||
anything at docs/ do. Hence, if a Thing replaces another, something has to go to
|
pnpx markdownlint-cli2 'docs/AGENTS.md' 'docs/current_roadmap.md'
|
||||||
the historical/.
|
|
||||||
|
|
||||||
as i said before. readme points to LIVE, Evolving docs. cant have stale/superseded stuff in here.
|
|
||||||
|
|
||||||
Same stuff for skills!
|
|
||||||
|
|
||||||
If a spec is still a useful design contract, update it in place. If it is only
|
|
||||||
"how we got here", move it to `historical/**`. Do not leave two docs claiming
|
|
||||||
different current behavior.
|
|
||||||
|
|
||||||
## Important rules
|
|
||||||
|
|
||||||
When moving or retiring docs, search for the old filename and update live links:
|
|
||||||
`docs/README.md`, `docs/current_roadmap.md`, skills, and nearby architecture
|
|
||||||
docs are the usual places.
|
|
||||||
|
|
||||||
If code has a partial implementation and docs mention the limitation, add a
|
|
||||||
short comment or docstring at the code seam too. Future agents see code before
|
|
||||||
they see old plans.
|
|
||||||
|
|
||||||
# docs formatting
|
|
||||||
|
|
||||||
## (caution: unstable) markdown formatting
|
|
||||||
|
|
||||||
use `pnpx markdownlint-cli(2) --fix '(glob the md)'`
|
|
||||||
<!-- ill need to setup cli2 -->
|
|
||||||
|
|
||||||
Note that this will mess things up, if you dont already follow the strict rules of markdownlint
|
|
||||||
|
|
||||||
use `git restore docs/historical` afterwards
|
|
||||||
|
|
||||||
### pitfall
|
|
||||||
|
|
||||||
all about indenting.
|
|
||||||
|
|
||||||
````md
|
|
||||||
1. you have a list, ordered or not?
|
|
||||||
|
|
||||||
this line ends the list, because it has no indents.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
## even this code block has to be indented
|
|
||||||
```
|
```
|
||||||
|
|
||||||
2. otherwise this will be "fixed" and renumbered to 1.
|
Use narrow lint or fix targets. Broad autofixes can rewrite historical files or
|
||||||
|
unrelated user changes.
|
||||||
|
|
||||||
<!-- in case -->
|
Follow CommonMark list indentation. When a Markdown example contains fenced
|
||||||
9. we have come far
|
code, wrap the outer example in a fence of four or more backticks.
|
||||||
- notice the indents
|
|
||||||
<!-- a blank line here is standard -->
|
|
||||||
10. after this point
|
|
||||||
- the indent increases
|
|
||||||
- since the list marker is longer
|
|
||||||
````
|
|
||||||
|
|
||||||
### why not prettier? it does much more
|
Treat excerpt-only Python blocks as prose examples, not formatter input. For
|
||||||
|
example, Ruff can reinterpret a lone `arg3=None,` argument fragment as an
|
||||||
when prettier supports compact table i'll switch to it
|
assignment because the surrounding call is absent.
|
||||||
|
|||||||
+2
-2
@@ -14,8 +14,8 @@ implementation plans are kept for context, not as active instructions.
|
|||||||
maintained thesis/report document.
|
maintained thesis/report document.
|
||||||
- [`thesis/evidence-index.md`](thesis/evidence-index.md): claim-to-code and
|
- [`thesis/evidence-index.md`](thesis/evidence-index.md): claim-to-code and
|
||||||
claim-to-test evidence map for the thesis.
|
claim-to-test evidence map for the thesis.
|
||||||
- [`current_roadmap.md`](current_roadmap.md): active next-work list after the
|
- [`current_roadmap.md`](current_roadmap.md): active implementation order,
|
||||||
core type-shape cleanup.
|
durable constraints, and links to historical context.
|
||||||
- [`wf_core_architecture.md`](wf_core_architecture.md): kernel package
|
- [`wf_core_architecture.md`](wf_core_architecture.md): kernel package
|
||||||
boundaries, runtime flow, validation flow, and known runtime gaps.
|
boundaries, runtime flow, validation flow, and known runtime gaps.
|
||||||
- [`wf_api_architecture.md`](wf_api_architecture.md): workflow application API,
|
- [`wf_api_architecture.md`](wf_api_architecture.md): workflow application API,
|
||||||
|
|||||||
+109
-937
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user