capturing-conventions

Capturing Conventions

Overview

Two entry points to the same destination — .neatcode/skills.yaml:

1. Per-utterance capture (the magic moment). User mid-flow says "every controller method must have @Throttle going forward." The keyword classifier triggers, propose_rule_from_prompt structures the rule, the user confirms, the rule lands.
2. Bulk mining (the orientation moment). Fresh repo, no captured rules yet. The user wants to know what conventions exist. Call derive_candidates to pull a graph snapshot, reason through it yourself, surface candidates conversationally, persist with accept_derived_candidates.

This skill calls propose_rule_from_prompt for the first path, derive_candidates + accept_derived_candidates for the second.

Trigger

Activate when the user's most recent message contains any of these rule-language tokens:

• must
• never
• always
• going forward
• no longer
• forbid
• require
• cannot
• shouldn't / should not
• don't / do not

The keyword classifier is deterministic. There is no LLM judgment in the trigger — if the keyword appears, the skill considers the message a candidate.

Procedure

Step 1: Call propose_rule_from_prompt

Pass the user's exact phrasing as the text argument:

propose_rule_from_prompt({ text: "<the user's message verbatim>" })

The tool returns one of two shapes:

a) No rule could be extracted:

{ proposed: null, reason: "<short explanation>" }

Stop. The keyword classifier had a false positive. Do not interrupt the user. Continue with whatever the user actually asked for.

b) A structured proposal:

{
  proposed: {
    id: "<slug>",
    primitive: "annotation-required" | "naming-pattern" | "folder-naming-convention",
    when: { kind, parent_has_annotation?, has_annotation_any?, name_suffix?, path_glob? },
    require: "<value>",       // primitive-specific
    scope: "new" | "all",
    source: "prompt"
  }
}

Step 2: Surface the proposal to the user