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.
|
||||
`superpowers/plans/` is only for executable handoff plans that are active or in
|
||||
progress.
|
||||
Use these locations consistently:
|
||||
|
||||
DONE docs go straight to [`historical/`](historical/). Prefer keeping the OG
|
||||
path shape under `docs/historical/`, for example
|
||||
`docs/superpowers/plans/foo.md` -> `docs/historical/superpowers/plans/foo.md`.
|
||||
You can edit the top of the file to state that its historical, but just being
|
||||
in the folder is enough.
|
||||
- `superpowers/plans/` contains active executable implementation plans.
|
||||
- `superpowers/specs/` contains current design contracts.
|
||||
- `historical/` contains completed plans, superseded designs, and narrative
|
||||
history. Preserve the original path below `historical/` when practical.
|
||||
|
||||
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/**`,
|
||||
live docs must point to `historical/**` when they cite old slice plans.
|
||||
Update user-facing documentation and repository skills when behavior changes.
|
||||
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
|
||||
historical context unless they are actively being used to drive this exact next
|
||||
slice.
|
||||
## Verify Markdown edits
|
||||
|
||||
## 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
|
||||
anything at docs/ do. Hence, if a Thing replaces another, something has to go to
|
||||
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
|
||||
```powershell
|
||||
pnpx markdownlint-cli2 'docs/AGENTS.md' 'docs/current_roadmap.md'
|
||||
```
|
||||
|
||||
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 -->
|
||||
9. we have come far
|
||||
- notice the indents
|
||||
<!-- a blank line here is standard -->
|
||||
10. after this point
|
||||
- the indent increases
|
||||
- since the list marker is longer
|
||||
````
|
||||
Follow CommonMark list indentation. When a Markdown example contains fenced
|
||||
code, wrap the outer example in a fence of four or more backticks.
|
||||
|
||||
### why not prettier? it does much more
|
||||
|
||||
when prettier supports compact table i'll switch to it
|
||||
Treat excerpt-only Python blocks as prose examples, not formatter input. For
|
||||
example, Ruff can reinterpret a lone `arg3=None,` argument fragment as an
|
||||
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.
|
||||
- [`thesis/evidence-index.md`](thesis/evidence-index.md): claim-to-code and
|
||||
claim-to-test evidence map for the thesis.
|
||||
- [`current_roadmap.md`](current_roadmap.md): active next-work list after the
|
||||
core type-shape cleanup.
|
||||
- [`current_roadmap.md`](current_roadmap.md): active implementation order,
|
||||
durable constraints, and links to historical context.
|
||||
- [`wf_core_architecture.md`](wf_core_architecture.md): kernel package
|
||||
boundaries, runtime flow, validation flow, and known runtime gaps.
|
||||
- [`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