torben
0fb8fd6122
Files changed: - CHANGES.md - VERSION - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/wiki-ingest/SKILL.md - instructions/wiki-lint/SKILL.md - instructions/wiki-manage/SKILL.md - instructions/wiki-query/SKILL.md - instructions/wiki-status/SKILL.md - tools/CONTRACT.md - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/instructions_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_instructions_cmd.py
119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
---
|
|
name: wiki-manage
|
|
description: Create a new wiki page (entity, concept, source, comparison) or update an existing page with new information, including cross-references, index/log, and publish. Use when the user says "create a new entity/concept/comparison", "add a page for X", "update the X page", or new information needs integrating into an existing page.
|
|
---
|
|
|
|
# Wiki Manage
|
|
|
|
**Purpose:** Create a new wiki page, or update an existing one, keeping cross-references, the
|
|
catalog and the audit log in sync.
|
|
|
|
**Trigger:** User requests a new entity/concept/comparison page, or new information needs
|
|
integrating into an existing one.
|
|
|
|
**Before the first `wikitool` call:** `instructions/session-setup.md`.
|
|
|
|
**Read before drafting:** `kb/CONTRACT.md` - linking and provenance,
|
|
both of which the tool enforces - and
|
|
`kb/CONVENTIONS.md`, which is where this instance's language, naming
|
|
forms, tone and relationship labels are, together with the target collection's own
|
|
`COLLECTION.md`, which carries its quality goal and what is local to that subtree. Field-level
|
|
requirements come from `tools/wikitool types describe <type>`.
|
|
|
|
## Creating a page
|
|
|
|
1. **Check it does not already exist.**
|
|
|
|
```bash
|
|
tools/wikitool search "<name and its synonyms>"
|
|
```
|
|
|
|
A near-duplicate under a different title is the most expensive mistake here, and the
|
|
cheapest to prevent. `search` does not count against the iteration budget.
|
|
|
|
2. **Determine the type.** `tools/wikitool types list` for the roster;
|
|
`tools/wikitool types describe <type>` for its required fields, enums and authoring
|
|
guidance.
|
|
|
|
3. **Scaffold it.**
|
|
|
|
```bash
|
|
tools/wikitool new <type> --name "<Name>" --set field=value ...
|
|
```
|
|
|
|
This resolves location, frontmatter, naming collisions and directory placement
|
|
deterministically. Never write frontmatter or pick a directory by hand.
|
|
|
|
4. **Gather what the wiki already knows** - `tools/wikitool search` again, for the surrounding
|
|
subjects - so the prose connects to existing pages instead of restating them.
|
|
|
|
5. **Draft.** Fill in the generated skeleton's TODO sections, following the tone rules in
|
|
`kb/CONVENTIONS.md` § Tone. If `provenance:` is `sourced` or `mixed`, cite
|
|
hard facts as you write them with `tools/wikitool cite add --page "<Title>" --source
|
|
"Source - X"`, which also adds `X` to `sources:` - paste the `[^cite-id]` marker it prints.
|
|
|
|
6. **Cross-reference.**
|
|
|
|
```bash
|
|
tools/wikitool xref add --a "<A>" --b "<B>" --rel-a "<label>" --rel-b "<label>"
|
|
```
|
|
|
|
One per relationship. Never hand-edit `related:`.
|
|
|
|
7. **Close out.** `instructions/publish-cycle.md`, `--op create`.
|
|
|
|
## Updating a page
|
|
|
|
1. **Read the page.** Understand what it already claims.
|
|
|
|
2. **Preserve what is still true.** Do not remove valid information to make room.
|
|
|
|
3. **Integrate the new content.**
|
|
|
|
4. **Mark what was superseded** - ~~strikethrough~~ for replaced text, or move it to a
|
|
"Historical" section with a note. Do not silently delete a claim that was once true; the
|
|
wiki's value is that it records what changed.
|
|
|
|
5. **Cross-reference** any new relationship (`xref add`), and cite any new hard fact inline.
|
|
|
|
6. **Update the frontmatter that describes the page itself:**
|
|
|
|
```bash
|
|
tools/wikitool touch --page "<Title>" --summary "<new 1-liner>" [--provenance <value>]
|
|
```
|
|
|
|
Never hand-edit `modified:`, `summary:` or `provenance:`.
|
|
|
|
7. **Close out.** `instructions/publish-cycle.md`, `--op update`.
|
|
|
|
## Renaming, deleting, or unlinking
|
|
|
|
That is `instructions/page-lifecycle.md`. A title is the wiki's only identifier for a
|
|
page, so none of it is a file operation.
|
|
|
|
## Decision points
|
|
|
|
- **Is this really a new page?** If the subject already has one, update it. If the material is
|
|
a head-to-head evaluation, it is a comparison and both subjects need pages first.
|
|
- **Entity or concept?** A thing you can point at is an entity; a *why* or *how* is a concept.
|
|
The collection contracts draw the line.
|
|
- **`publish` refused?** A single page is normally well under the threshold. If it trips,
|
|
`instructions/gates.md`.
|
|
|
|
## wikitool commands used
|
|
|
|
`search`, `types list`, `types describe`, `new`, `touch`, `cite add`, `xref add`, `xref remove`,
|
|
`sources rebuild-index`, `index rebuild`, `log append`, `publish`
|
|
|
|
`xref remove` belongs to the unlinking case, which this skill delegates whole to
|
|
`instructions/page-lifecycle.md` rather than describing in a step of its own.
|
|
|
|
## Output
|
|
|
|
A new or updated page, published to `origin/main`.
|
|
|
|
**Example triggers:**
|
|
|
|
- "Create a concept page for the deployment pipeline we just discussed"
|
|
- "Update the Index Scaling page with what the new lint run showed"
|