grimoire-note

[Required Reading]

1. Read ${CLAUDE_PLUGIN_ROOT}/GRIMOIRE-CONVENTIONS.md. Only § Skill composition, § Project context, § IDE-aware review, and § Commits apply to this skill. § TDD, § Sub-agent spawning, § Historic, § User-facing language, § Pause-point pattern (for pipeline pages), and § .grimoire/ layout (for pages) do not apply — this skill is orthogonal to the Spec → Plan → Execute pipeline, never creates a page folder, never touches HISTORIC.md, and never spawns execute sub-agents.
2. If .grimoire/PROJECT.md exists in the project root, read it for project context — defer the hard-stop check to Phase 1 below so the user-facing message is presented cleanly.

[Objective] Fold the user's free-text note(s) into .grimoire/PROJECT.md with surgical, incremental edits restricted to ## Key Conventions / Constraints and ## Notes. Never rewrite the whole file, never add a new section, never regenerate a skeleton — only sharpen what is already there or append a single well-phrased entry.

$ARGUMENTS

[Hard constraints]

• Only .grimoire/PROJECT.md may be edited. No other file in the repo is touched.
• Only ## Key Conventions / Constraints and ## Notes may be modified. Never add, rename, or remove any section header. Never edit ## Purpose, ## Audience, ## Tech Stack, ## Repository Layout, or ## Current Status.
• Never create .grimoire/PROJECT.md if it is missing — hard-stop instead.
• Never create a page folder, never write to .grimoire/HISTORIC.md, never spawn execute sub-agents.

[Phase 1: Precondition Check (HARD STOP)] Verify .grimoire/PROJECT.md exists at the project root. If it is missing, print the canonical English message verbatim:

❌ .grimoire/PROJECT.md does not exist. grimoire-note edits the Key Conventions and Notes sections of PROJECT.md — without the file there is nowhere to write. Run /grimoire-init first to create the base context, then re-invoke /grimoire-note.

The message may also be rendered in the user's interaction language when detected (e.g., pt-BR); English is the default and the canonical reference. STOP. Do not offer to run grimoire-init automatically. Do not create a skeleton.

[Phase 2: Input Parsing & Semantic Split] Parse the user's free-text input. Semantically split it into N distinct rules when the input carries several (e.g., two sentences encoding two unrelated conventions). Single-rule inputs stay as one entry. Produce a structured list internally — the user-facing surface of the split happens at Phase 6 ("Detected N distinct rules: …").

[Phase 3: Read & Synthesize Against Existing Sections] Read ## Key Conventions / Constraints and ## Notes in full from .grimoire/PROJECT.md. For each rule from Phase 2, run a semantic pass against every existing entry in both sections to detect:

• Duplication — the new rule already exists verbatim or in spirit.
• Refinement — the new rule sharpens or constrains an existing one.
• Generalization — the new rule subsumes (or is subsumed by) an existing one.
• Contradiction — the new rule conflicts with an existing one.

For each detected relationship, propose the best synthesis: merge, rewrite, generalize, or accept as new. Minimum-word phrasing is an explicit objective — favor terse, declarative entries over verbose ones, and prefer rewriting two near-duplicate lines into one over appending a third.

[Phase 4: Retroactive Consolidation Pass] Independently of the new input, scan all existing rules in both sections and propose rewrites where synthesis can be improved: consolidate near-duplicates already on the page, tighten verbose phrasings, merge adjacent rules that say the same thing. This pass runs every invocation, not just when the new input triggers it — the cost is acceptable because the synthesis discipline keeps the file naturally small.

[Phase 5: Section Assignment] Assign each accepted rule to its section using this heuristic: