greprag 5.60.13 → 5.61.0

package/skill/templates/os.md

@@ -0,0 +1,74 @@
+# grepragOS — the operating laws
+
+How to work WITH greprag, not just use its tools. The tool primers (inbox,
+load, email, corpus, memory) teach each surface; this entry is the layer above
+them — the behavior that makes everything you build discoverable, durable, and
+fixable by the next session. Tenant-agnostic: these laws are the same for
+every operator, every project, every harness.
+
+## Law 1 — Doctrine vs state
+
+Doctrine (methods, skills, playbooks) ships in the CLI and is served by
+`greprag load`. Live state (status files, records, project data) lives in the
+repo. Never blur them: a skill is not a place for today's numbers, and a repo
+doc is not a place for a reusable method.
+
+A skill that depends on repo state MUST bridge the gap explicitly — carry a
+**"STATE — read these first"** block naming the exact repo paths
+(`docs/<area>/status.md`, not "the status doc"). `greprag load <skill>` then
+delivers both the method AND the map to the live state. Full paths only: a
+bare filename collides with bundled companion docs.
+
+## Law 2 — Discoverability
+
+Every durable artifact must be findable by a session that has never seen this
+conversation. The registration is part of the work, not an extra:
+
+- **Docs** auto-register (the doc-pointer system rides the Stop hook) — but
+  only if you write them as real `.md` files in the repo.
+- **Skills** auto-mirror on use (`greprag load` serves them cross-machine).
+- **Decisions** get a dated entry in the owning ADR / decision log, in the
+  same commit as the code.
+- **Everything else** (state files, artifacts, conventions) gets its path
+  named in the owning skill or doc (Law 1's STATE block).
+
+Test: if you made it and nothing points at it, you didn't finish.
+
+## Law 3 — Pull before derive
+
+Before asking the operator or re-deriving what the project already knows:
+`greprag memory search "<topic>"` (past sessions), `greprag corpus search`
+(reference banks), `greprag load` (the method catalog). Searching is cheap;
+re-explaining is expensive; guessing is worst.
+
+## Law 4 — Friction ⇒ fix spawn, at the moment
+
+Friction — you repeated yourself, fought a tool, got corrected twice on the
+same thing, rediscovered something already known, hit a setup failure that
+wasn't your edit — is fixed at the MOMENT it happens:
+
+    greprag fix spawn "<one unit of friction>"
+
+- **One unit = one chip.** A fix chip exists for exactly one unit of
+  friction. Adjacent friction gets its own spawn — a chip that absorbs new
+  friction loses the context each unit needs.
+- **The chip's contract** (it self-enforces): INVESTIGATE first — reproduce,
+  locate the root mechanism, draft the durable repair, score confidence
+  0–100. Then the gate: **≥90** → implement, test, commit, report DONE.
+  **<90** → STOP, park with findings + options, co-design the repair with
+  the operator before touching code. Rarely can a chip design the durable
+  repair alone; the gate is what keeps repairs durable instead of
+  workarounds.
+- **Never queue friction for later.** The queue-first reflex (`fix log` →
+  periodic digestion) is retired; the moment that produced the friction
+  holds the context the fix needs. `greprag fix log` survives only for
+  audit trails and design-input notes that are deliberately not chips.
+- Every repair is ROOT-CAUSE: fix the pattern that makes the friction class
+  possible, never a guard on today's trigger.
+
+## Law 5 — Teach the system, not the chat
+
+If the operator explains the same thing twice, the explanation belongs in a
+durable surface — a skill, a load entry, a STATE block, an ADR — not in the
+conversation. Hand-taught doctrine that stays in chat dies with the session;
+that is itself friction (Law 4 applies).