Skip to main content

Writing Project Knowledge

Plugin: TSH Product Management
Invoke: /tsh-product-management:writing-project-knowledge (also model-invocable: it routes on "write this down", "document this", "update the doc on X" in a project with a *-context repository)
Used by: Navigating Project Context names it as the only route for changing the knowledge base from work in a code repository. No agent loads it.

Writes into the project's knowledge base under the rules of the workspace that owns the topic. The failure it prevents is a second document saying something different: knowledge added beside the existing document instead of into it.

When it applies​

  • Recording a requirement, constraint, integration detail or process change.
  • Correcting a document that no longer matches reality.
  • A workshop or call that produced knowledge worth keeping.

What it covers​

AreaCoverage
Isolated writeEvery change is made in a separate worktree on a new branch docs/<topic>, beside the person's clone. The person's clone is never edited, whatever branch it is on, except for a knowledge base with no remote yet (see The branch flow)
Owning workspaceReads docs/README.md, picks the one workspace whose scope covers the topic, then reads that workspace's CLAUDE.md for its owner and rules. When two fit, it chooses the one that owns the outcome and says which it rejected
Update, don't addReads the workspace README.md and the documents it names first. Updating a document in place beats adding another; a file is created only when nothing covers the topic
State of todayPresent tense, current state, no history; history lives in version control. A document the change makes wrong is fixed in the same change, deleted, or given a DEPRECATED banner with a pointer to the successor
IndexThe entry in the workspace README.md is added or adjusted in the same change; a document nothing links to will not be found
Checksscripts/check_links.py and scripts/check_tables.py run from the worktree until clean
ReviewThe report names the workspace, the files, the branch, and the owner from that workspace's CLAUDE.md who reviews it. The change reaches everyone only after the pull request is merged
DecisionsNever recorded here. A choice with alternatives goes to Managing Decision Records with the worktree's docs/decisions/ as the archive, never a code repository's own folder. This skill never sets or changes a record's status

The deprecation banner, placed under the document's title:

> **DEPRECATED (YYYY-MM-DD).** <Why this no longer describes the current state.>
> Current state: [<successor>](path).

How it works​

  1. Locate the knowledge base and open a branch. Resolve and sync KB through the shared guide, propose the branch with write_worktree.py start, and create it only after the person answers Create. The worktree is called W; everything is read and written under W.
  2. Find the owning workspace in W/docs/README.md, then read its CLAUDE.md. Its rules outrank this skill.
  3. Look for the document that already exists.
  4. Write it, in kebab-case filenames, linking only to files that exist in the repository. Fix or banner anything the change contradicts.
  5. Update the index in the workspace README.md.
  6. Verify, then commit and push only on a yes: both checkers, then the Commit and Push questions.

The skill never invents a fact to fill a gap: it writes what is known and names the gap as a gap.

The branch flow​

Shared by Adding a Project-Context Workspace and Repairing Project-Context Links. Each git step runs only after its own yes; one yes never covers another step. Every question names where the change lands and whether it stays on this machine.

StepScript callQuestion and effect
Proposewrite_worktree.py start <KB> docs/<topic>Changes nothing; prints the proposed worktree, branch, base, base commit and remote
Createstart <KB> <branch> --yes --at <sha>Create / Cancel. Creates the worktree at the confirmed commit. The person's own copy stays untouched; nothing is sent
Write and checknoneIn W, as the skill says
Commitcommit <W> --message <text> --yesCommit / Change something / Cancel. Commits in W; stays on this machine
Pushpush <W> --yesPush / Keep local. Sends the branch for review; the base branch changes only when someone merges the pull request. On Bitbucket and GitHub the push output carries the pull-request link, and the person opens it

The worktree is placed at <KB parent>/<KB name>-worktrees/<branch>, with each / in the branch name replaced by - (for example ...-worktrees/docs-payments). push refuses the default branch, a detached HEAD and uncommitted changes, and never forces. On Cancel or Keep local the skill stops and says where the work is; the worktree and branch stay on this machine and are never deleted by the skill.

  • No remote yet. For a knowledge base that exists only on this machine (a lead starting alone) there is nothing to branch from. Only if KB has no uncommitted changes, the skill asks Write and, on yes, writes directly in KB and commits there. The change exists only on this machine until the project gets its URL.
  • Refusals. start exiting 1 means the remote could not be asked (offline, no access): the skill stops and never falls back to writing in KB. A name that is taken gets docs/<topic>-2 proposed. commit or push failing shows the message and stops; it never retries differently, forces, or runs git by hand.

Rules​

SeverityRule
MUSTRead the target workspace's CLAUDE.md before writing
NEVERAdd a document that contradicts a live one
NEVERRecord a decision, or set or change a record's status
MUSTUpdate the workspace README.md index in the same change; leave both checkers passing; name the reviewing owner
NEVERCreate the branch, commit or push without that step's own yes; write in the person's clone (except for a knowledge base with no remote yet); push to the default branch; open, merge or approve the pull request
NEVERInvent a fact to fill a gap

Source​