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)