simonpokorny/knowledgebase

Write one small, schema-clean entry into the repo's .knowledgebase/. If the repo has no .knowledgebase/, stop and tell the user to run the /setup-knowledgebase skill first.

1. Pick the type:

   It is	Type	Path
   a claim about the system, true and worth not rediscovering	finding	.knowledgebase/entries/finding-<topic-kebab>.md
   a rule of behavior, usually born from a mistake	learning	.knowledgebase/entries/learning-<topic-kebab>.md
   a choice between alternatives, with a trade-off	decision	.knowledgebase/entries/decision-NNNN-<topic-kebab>.md

2. Write the entry. The frontmatter fields, statuses, limits, and body conventions are in ENTRY-FORMAT.md; read it before writing. Worked examples ship in this plugin's templates/ directory.

3. Check the status is honest. For findings and learnings: verified only when you proved the claim yourself in this session, and then set verified-by: agent and put the evidence in the body (a Source link or the check you ran). Anything you could not prove stays unverified; those are the entries the human is asked to verify in review. New decisions get status: decided and come in two kinds:

   • Implementation decisions: fundamental choices you made yourself while building. Record them with the why and the trade-off, as decided-by: agent.
   • Planning decisions: made together with the user, not inferable from the code. Record them as decided-by: agent too, then hand the user the adopt line from the session-end report so the entry becomes decided-by: human. Never set decided-by: human yourself; only a human does. Either kind can later be superseded by a newer decision.

4. If the entry is a learning that forbids a command, add a guard: regex so the rule enforces itself. Guard-writing rules are in ENTRY-FORMAT.md; test the regex with grep -E before committing.

5. Commit the entry on the same branch as the change that produced it, so it rides the same commit. Do not batch entries for later.