Bumblebiber/o9k-new-rule

/o9k-new-rule — Place a Rule in the Right Place

R-prefix entries are surfaced in the session-start Rules listing for every session. A project-specific rule written as an R-entry leaks into other projects' context. A cross-project rule buried inside one project never surfaces when working on another. Same content, very different consequence — scope decides.

Step 1: Determine scope BEFORE writing

Ask the user, unless they already said:

"Gilt die Regel projektübergreifend (alle Projekte) oder nur für das aktive Projekt?"

Suggest a default from these heuristics:

| Signal | Likely scope | |--------|-------------| | Rule names a specific repo path, file, CLI tool, schema field, project's tech stack | Project-specific | | Rule mentions hmem code, propagation to end users, project structure | Project-specific (P0048-specific) | | Rule is about agent behavior, communication style, write protocols, MCP interaction | Cross-project (R) | | Rule references infrastructure used in many projects (e.g. Strato server, npm publish in general) | Cross-project (R) | | Rule applies only when one specific project is active | Project-specific |

When in doubt, ask. Wrong scope is the most common failure mode of this workflow.

Step 2A: Cross-project rule → R-entry

write_memory(
  prefix="R",
  title="<short imperative title>",
  body="<full rule text — what / why / examples / counter-examples>",
  tags=["#hmem", "#<topic-tag>"],
  links=["<active-project-id-if-relevant>"],
  pinned=<true only if it MUST surface in session-start every session>
)

• links may include a project ID for context, but the rule still applies broadly.
• pinned=true only when the rule belongs in the always-visible Rules block at session start (after the v6.x hook trim, only pinned/favorite R-entries surface). Use sparingly — pinning everything defeats the purpose.

Step 2B: Project-specific rule → subnode under Rules

First check whether the active project has a Rules section:

read_memory(id="P00XX")     # look for an L2 child titled "Rules"

If a Rules L2 exists (e.g. P0048.16):

append_memory(
  id="P0048.16",
  title="<short imperative title>",
  body="<full rule text>"
)

If no Rules L2 exists, create it with the rule as its first child by leveraging the schema-name exception (root append is allowed when the first line names a section):

append_memory(
  id="P00XX",
  content="Rules\n\t<short imperative title>\n\n\t<full rule text>"
)

Project-specific rules need no tags or links (project-scoped by location) and should never be pinned (visibility is already scoped via the active project).

Step 3: Verify

read_memory(id="<the-new-id>")

Confirm title + body are stored correctly. If anything looks off, fix with update_memory immediately.

Anti-patterns

| Mistake | Why it hurts | |---------|-------------| | Writing R-prefix for a one-project rule | Leaks into every other project's session-start Rules block | | Writing P00XX.Rules.X for a workflow rule that applies to all projects | Invisible whenever a different project is active | | Pinning a project-specific rule | Already scoped by project; pinning forces it cross-project anyway | | Setting obsolete=true without [✓ID] | Blocked by write protocol — write the correction first | | Skipping the scope question because "it's obvious" | The previous offender did this and wrote R0028 for a P0048-only rule |

Related

• /o9k-write — lower-level write_memory / append_memory protocol, prefix selection, tag conventions
• /o9k-curate — fix misplaced rules afterwards (mark irrelevant + move content)