rem-page-project · diff
git:20261010.f3bc74b to git:20261015.6c0dec1
93 added, 78 removed. Audit A to A.
---
name: rem-page-project
- description: A project page with a short visual overview and evidence-backed detail.
+ description: A project page a new teammate understands in one screen: what it is, why, where it stands, what is next.
---
# A project's page
+ Write for a teammate who has one minute. The first screen answers, dated and
+ cited: what the project is, why it exists in the owner's words, where it
+ stands now, and what is still open. Reference detail follows. A page that
+ tours files and hedges every line fails even when every line is true.
Read the page and material. Write once, check once, fix once, stop.
- Do not search examples, logs or the repo for a format.
+ Search the repo for evidence, not for a format: this Skill is the format.
- Explain purpose and flow first, for a new teammate.
- After investigation, **keep the core headings** `Facts`, `Insight`, `What it is`,
- `Where it stands`, `Paths`, `Open threads`, `Uncertainties`, and `Sources`.
- Use the other headings only when evidence fills them; omit an optional heading
- whose whole body would be `Unknown`. Keep the following order for those shown:
+ Keep the core headings `Facts`, `Insight`, `What it is`, `Where it stands`,
+ `Open threads`, `Paths`, `Uncertainties` and `Sources`. Show any other heading
+ only when evidence fills it; omit one whose whole body would be `Unknown`.
+ Keep this order for those shown:
```markdown
# <Name>
## Facts
## Insight
## What it is
- ## Overview
-
- ## Try it
+ ## Why it exists
## Where it stands
+ ## Open threads
+
## Latest issues
- ## People and ownership
+ ## Key decisions
- ## Getting started
+ ## Overview
- ## Why it exists
+ ## Try it
- ## Key decisions
+ ## People and ownership
+ ## Getting started
+
## How it is built
## Architecture map
## Paths
- ## Open threads
-
## Uncertainties
## Sources
```
- **Facts and Insight first**
+ **Facts**: one line a field, labels exact, all present, missing exactly
+ `Unknown`: `Repository`, `Stack`, `Status`, `People`, `Organisation`,
+ `Started`, `Last activity`. Several values `; ` between, each
+ `value (qualifier) [n]`; dates `YYYY-MM-DD`; every value cited.
+ - `Status`: a phrase the evidence earns: `active — commits weekly on
+ origin/main`, `quiet since 2026-08-10`, `exploring, nothing chosen`.
+ - `Last activity`: the newer of the latest commit on the current line and
+ the latest message that names this project, with what it was:
+ `2026-10-15 — Gemini 4 Argon made selectable (commit e25df6e) [n]`.
+ - `Started`: the first commit or the owner's words that began it; the first
+ observed session is not a start.
- - `Facts`, one line a field, labels exact, all present, missing exactly
- `Unknown`: `Repository`, `Stack`, `Status`, `People`, `Organisation`,
- `Started`, `Last activity`. Several values `; ` between, each
- `value (qualifier) [n]`; dates `YYYY-MM-DD`; every value cited.
- - `Insight`: 2–4 cited bullets of at most 30 words, starting `Now:`, `Changed:`,
- `At stake:` or `Pattern:`. Lead with a verified state, mismatch or decision
- or requirement change that matters to the user. Read the local
- repository packet first. When its README, manifest, checkout or commits bear
- on a dated user message, join them in one bullet and cite both. If unrelated,
- keep them separate; do not infer no fix from commit subjects. Checkout
- freshness alone is housekeeping, not the lead. `Changed:` needs a verified
- change; label changed requirements as requirements. A local commit does not
- prove tests or deployment. Thin material: `- Unknown`.
- With requests only, surface precise operating constraints; preserve branch
- versus organization scope.
+ **Insight**: 2–4 cited bullets of at most 30 words, starting `Now:`,
+ `Changed:`, `At stake:` or `Pattern:`: what changes a teammate's next
+ decision. Compare the owner's words with the repository first: a requirement
+ the code contradicts or has not caught up with (the owner says 8% of net, the
+ PDF says gross), a reversed choice, a requirement that moved. What the code
+ does belongs in `What it is`; a branch, commit date or README topic is not an
+ insight. None: `- Unknown`.
- **Opening**
+ **What it is**: one or two sentences: the product, who it serves, what it
+ does, from the README or the owner's description of the whole project, never
+ the loudest recent thread.
- - `What it is`: one sentence naming a verified product and purpose, or state
- the user's requested work as a goal when product identity is unverified.
- - `Overview`, when supported: 3–7 narrow-screen ASCII steps in a `text` fence,
- showing user start, actions and outcome. Modules go in `Architecture map`.
- - `Try it`, when supported: entry point, tiny example and visible result,
- at most three steps. Say if access is needed. No invented URLs, runs or credentials.
+ **Why it exists**: the problem and intended outcome, opened with the owner's
+ words that started it or best state its purpose:
+ `YYYY-MM-DD — “<exact words>” [n]`. The newest request is not why a project
+ exists; without such words, quote the README's purpose, dated by its revision.
- An unknown flow is omitted; a plausible diagram is not evidence.
+ **Where it stands**: 3–5 bullets about now, newest first, each dated: the
+ latest finished work (commit subjects on the current line, the owner's
+ latest messages; quiet for weeks — say so); work in flight (recent unmerged
+ branches, by name and date); the phase and goal; the latest run, test or
+ deploy result someone reported, or none found. History goes in `Key decisions`.
- **Current work and joining the team**
+ **Open threads**: only what is pending now, newest first:
+ `- YYYY-MM-DD — <who> asked: “<exact words>” [n] — open|blocked on <what>`.
+ Before listing an ask, look for its outcome in later messages, commit
+ subjects and branch names. One closed by a commit or a later message moves to
+ `Where it stands` or `Key decisions` with that evidence. An ask more than 30
+ days old with no outcome found is history, not an open thread: leave it out.
+ Nothing open: bare `Unknown`, never a "no pending work" line.
- - `Where it stands`: 3–5 bullets, now, not a log: project-relevant activity date (say if
- quiet for months); current phase and goal; latest verified run or test result
- with date, or none found. The past goes in `Key decisions`.
- - When shown, `Latest issues` lists bugs, regressions, blockers, newest first: date, symptom,
- impact, status, evidence, next step. A report is not a diagnosis; a proposed
- fix is not a resolution.
- - When shown, `People and ownership` says who to ask, by area, where known; link person pages.
- Never infer someone else's ownership from one commit or message; the user's
- sessions identify the requester, not a project ownership role.
- - When shown, `Getting started` is per relevant role (designer, engineer, operator); commands
- and expected outputs only when verified.
+ **Latest issues**: bugs, regressions, blockers, newest first: date, symptom,
+ status with its evidence. Check the history for a fix before calling one
+ open. A report is not a diagnosis; a proposed fix is not a resolution.
- **Background and technical detail**
+ **Key decisions**: the choices the owner made, newest first, up to eight:
+ price, scope, audience, positioning, architecture, what to drop.
+ `- YYYY-MM-DD — <choice, under 12 words>: “<the owner's exact words>” [n]`.
+ A reversal is its own line quoting the reversal. A request alone or current
+ behaviour alone is not a decision; label proposals.
- - `Why it exists`: original problem, user needs, intended outcome, scope.
- - `Key decisions`: dated choices, why, tradeoffs, sources; label proposals and
- superseded ones. Current behaviour alone is not a decision.
- - `How it is built`: main components and responsibilities; link deeper docs.
- - `Architecture map`: ASCII diagram of verified modules and data flow; cite
- inspected paths and revision outside it; label proposed apart from built.
- - `Paths`: observed repositories, directories, design/doc locations, each with
- its purpose. Never guess paths.
- - `Open threads`: confirmed pending work, owner when known, date. Missing
- completion evidence is unknown status, not proof a historical request is open.
- - `Uncertainties`: missing, unread, stale or conflicting evidence, said once
- here rather than as a tail on every bullet elsewhere.
- - `Sources`: numbered, `- [n] <source id> — <date>`, nothing more; each inspected
- file its own entry. Mark inference; never copy facts from examples.
- Use supplied `source` IDs; `git:` origins and paths are not IDs. Dates do
- not establish project activity or release.
- Check inherited clauses, quantities and dates against exact originals,
- not summaries or adjacent inputs. Valid IDs are not support; cite each
- joined clause and both messages.
+ **Overview** and **Try it**, when the README, docs or code at the current line
+ show them: `Overview` is 3–7 narrow ASCII steps in a `text` fence (user start,
+ actions, outcome); `Try it` is an entry point, a tiny example and the visible
+ result, at most three steps, in the source's order. A plausible diagram is
+ not evidence; an unknown flow is omitted.
- Keep claims short. Omit mapper, collector, counts and prior-page metadata.
+ **People and ownership**: who to ask, by area, and the partners, clients or
+ collaborators the messages name on this project, linking person pages. One
+ commit or message never makes someone an owner.
+ **Getting started**: per role, commands and outputs only when verified.
+
+ **How it is built** and **Architecture map**: main components and data flow
+ from files at the current line, citing the revision; label proposed apart
+ from built. Short: a page is not a code tour.
+
+ **Paths**: the project's own folders (repository, data or design locations
+ outside it) with their purpose; modules belong in `How it is built`. Never guess.
+
+ **Uncertainties**: at most five, each one that would change the next step;
+ provenance limits are said once here, not on every bullet.
+
+ **Sources**: numbered, `- [n] <source id> — <date>`, nothing more; each
+ inspected file its own entry. Use supplied `source` IDs; `git:` origins and
+ paths are not IDs. Check inherited clauses, quantities and dates against
+ exact originals; cite each joined clause's own message.
+
**Two stages, one page**
Mapping writes observed metadata only; other sections stay
`Unknown — not investigated yet` until investigation fills them from evidence.
User-only coding transcripts show intent, not implementation or passing tests:
- verify those from repository or execution evidence. On an older page, add
- missing core sections and reorder to this shape, keeping supported optional
- content. Never reuse the architecture diagram as the overview. Leave the
- `Investigation:` line unchanged. Keep the mapped `Sessions`, `First seen` and
- `Last seen` fields in `Paths` exactly.
+ verify those from the repository or a reported run. On an older page, reorder
+ to this shape, keeping supported content. Never reuse the architecture
+ diagram as the overview. Leave the `Investigation:` line unchanged. Keep the
+ mapped `Sessions`, `First seen` and `Last seen` fields in `Paths` exactly.