laurence/itelescope
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Bootstrap: Default Workflow scaffold

Browse source 
Repo created for a reference/review of the iTelescope.net remote telescope
network. This commit copies the Default Workflow in (CLAUDE.md and docs/ from
the Default-Workflow repo), adds a .gitignore (secrets and scratch), and fills
in state/PROJECT.md with the objective: review every telescope on the network
and provide a choosing guide, using only public sources (support article and
the maintained Google Sheet; the go.itelescope.net launchpad is login-only).
This commit is contained in:
Laurence 2026-07-17 14:20:36 +01:00
commit 3fad877dee
7 changed files with 350 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

54
docs/documentation-policy.md Normal file
View file

@ -0,0 +1,54 @@
# Documentation policy
Two separate ideas, both about making the repo the single source of truth so that no
session ever depends on another session's chat history.
## A. State lives in committed markdown, not in the chat
Do not use chat history, context, or cache as memory. They cost tokens to carry and
vanish between sessions. Instead, everything a future session needs is written to the
`state/` directory and committed:
| File | Holds |
|------|-------|
| `PROJECT.md` | Objectives, scope, description, audience. The anchor. |
| `ARCHITECTURE.md` | How the system is built and why it is built that way. |
| `DECISIONS.md` | A dated log of decisions and their rationale. Append, never rewrite history. |
| `TODO.md` | Done / in progress / pending. The current state of play. |
| `NOTES.md` | Working notes, gotchas, environment quirks, dead ends to avoid. |
Update these as part of the work, not as an afterthought. A change to how the system
works is not finished until `ARCHITECTURE.md` or `DECISIONS.md` reflects it.
Templates for all of these are in `templates/`.
## B. Documentation is written in a separate session from the code
The user facing documentation (README, guides, API docs, changelog) is **not** written
in the same session that writes the code. This is deliberate:
- It forces the building session to leave a complete trail. If the code cannot be
documented later from git history and comments alone, the trail was not good enough.
- It keeps each session cheap and focused. A building session spends its budget
building; a documentation session spends its budget writing docs.
- It gives the docs a cold, independent reader who documents what the code actually
says, not what the author remembers intending.
### What the building session must leave behind
So the later documentation session can work with no chat history:
1. **Commit messages with full notes** - what changed, why, and any trade-offs. See
[Workflow](workflow.md).
2. **A complete PR description** - feature, tools used, what was achieved, how it works.
3. **Code comments that explain intent** - not what a line does (the code shows that)
but why it exists, what it assumes, and what would break it. Comment for a stranger
who was not in the room.
4. **Current `state/` files** - especially `ARCHITECTURE.md` and `DECISIONS.md`.
### What the documentation session does
Starts cold. Reads `git log`, the PRs, the code and its comments, and the `state/`
files. Writes the documentation from those alone. If something cannot be understood
from the repo, that is a gap to flag, not a reason to guess or to reach for lost chat
context.