Proposal Create

---
name: proposal-create
description: Creates a proposal for a high-leverage improvement discovered during work. Only for ideas with real impact — not trivial fixes. Use when you discover something worth operationalizing.
---
# Create Proposal

Create a proposal only when you discover something with real leverage:
- A missing helper or utility that would save significant time across sessions
- A missing validation or guardrail that could prevent real errors
- A workflow improvement that would benefit multiple sessions
- A reusable pattern worth operationalizing

## Three-Condition Rule

Only create a proposal if all three are true:
1. **Repeated pattern** — observed more than once, across sessions. **Skip for `scheduled-check/*`, `operator-request`, `current-session`, and `capability-brainstorm` evidence sources** — recurrence is either established by the check's own analysis, validated upstream by `reflection-judge`, or established by the brainstorm pass.
2. **Meaningful consequence** — something goes wrong without fixing it
3. **Operator-actionable change** — something the operator can concretely approve

If any applicable condition cannot be stated concretely, do not create the proposal.
Respond: "Not enough evidence yet. Note it in SHELL.md Findings and revisit after more sessions."

## Pre-Creation Gate

Before creating the proposal, call `claude-code-hermit:proposal-triage`. Pass `Evidence Source:` when known:
```
Title: <proposal title>
Evidence Source: <archived-session | current-session | scheduled-check/<id> | operator-request | capability-brainstorm>
Evidence: <one-paragraph evidence summary>
```

`Evidence Source:` is optional (default: `archived-session`).

Parse line 1 as the verdict. Lines 2+ are additive metadata (`closest_prop`, `aligned`, `operator_excerpt`, `overlap_compiled`, `prior_discussion`, `failed_condition`) — read for context if useful but do not branch on them.

After receiving the verdict, append one event to `state/proposal-metrics.jsonl`:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/append-metrics.js \
  .claude-code-hermit/state/proposal-metrics.jsonl \
  '{"ts":"<now ISO>","type":"triage-verdict","verdict":"<CREATE|SUPPRESS|DUPLICATE>","caller":"proposal-create"}'
```

- `CREATE` — proceed with the steps below
- `DUPLICATE:<PROP-ID> — <reason>`: stop, report to the caller: "Proposal already exists as <PROP-ID>"
- `SUPPRESS — <code>: <reason>`: stop, report the suppression reason to the caller

## How to Create

1. Determine the next proposal ID and creation timestamp:
   - List all `.claude-code-hermit/proposals/PROP-*.md` files
   - Extract the integer from each filename (regex `PROP-(\d+)`), take the max, add 1; zero-pad to 3 digits. If none exist, start at `001`.
   - Capture current time as `HHMMSS` (6 digits, zero-padded) in the `timezone` from `config.json`, or UTC if unset.
   - Canonical ID: `PROP-NNN-<slug>-HHMMSS` (e.g. `PROP-009-capability-brainstorm-103612`). This is what goes in frontmatter `id:` and in all cross-references. The ID equals the filename stem — there is no separate short form in the file.

2. Build the filename and create the proposal file:
   - Generate a slug from the title:
     a. Drop non-ASCII characters, lowercase.
     b. Replace every run of non-`[a-z0-9]` characters with a single space.
     c. Split into tokens; drop stopwords: `a an the and or of for to in on with by from as is are`.
     d. If filter leaves zero tokens, fall back to the pre-filter token list.
     e. Take the first 5 tokens; join with `-`; truncate to 40 chars at a word boundary (drop trailing tokens until ≤40 chars; if a single token exceeds 40, hard-cut it).
     f. If after all steps the slug is empty (title was all punctuation, all non-ASCII, or itself empty), use the literal `proposal` as the slug. The filename and id must never contain a double-dash like `PROP-009--HHMMSS`.
   - Target filename: `PROP-NNN-<slug>-HHMMSS.md` (e.g. `PROP-009-capability-brainstorm-103612.md`).
   - If the target filename already exists (same-second collision), append `a` to both the filename (`...-HHMMSSa.md`) and the `id` field (`PROP-NNN-slug-HHMMSSa`). On further collisions, continue through `b`, `c`, … in order.
   - Create `.claude-code-hermit/proposals/PROP-NNN-<slug>-HHMMSS.md` using `.claude-code-hermit/templates/PROPOSAL.md.template`:
   - Write YAML frontmatter with:
     - `id`: the canonical ID `PROP-NNN-<slug>-HHMMSS` (or `PROP-NNN-<slug>-HHMMSSa` if the collision guard fired) — equals the filename stem without `.md`
     - `status`: `proposed`
     - `source`: `manual` (default), `auto-detected` (when invoked by `reflect`), or `operator-request` (when triggered by a direct operator request). This field records **proposal origin only** — gate bypass is controlled by the caller-supplied `Evidence Source:` above, not by `source:`.
     - `session`: the current session ID (S-NNN)
     - `created`: current ISO 8601 timestamp with timezone offset (e.g., `2026-04-06T14:30:00+01:00`). Use the timezone from `config.json` if set, otherwise UTC.
     - `related_sessions`: relevant session IDs as YAML array (optional — used by auto-detected proposals to link evidence across multiple sessions). Use `[]` if none.
     - `category`: classify as one of:
       - `improvement` — workflow or tooling fix
       - `routine` — repeating scheduled task
       - `capability` — new agent, skill, or heartbeat item
       - `constraint` — OPERATOR.md refinement
       - `bug` — incorrect or broken behavior
     - `title`: short proposal title (same text used in the H1 heading after the dash)
     - `resolved_date`: `null` (set later by reflect when pattern is confirmed gone)
   - Fill in the title in the H1 heading
   - while writing the body: write a clear Context, Problem, Proposed Solution, and Impact
   - Leave "Operator Decision" blank — the operator fills that in
   - Do NOT write bullet-point metadata (`- **Created:**`, etc.) — all metadata lives in frontmatter only

3. Add a reference to the proposal in `.claude-code-hermit/sessions/SHELL.md` under the Findings section

4. Append a `created` event to proposal metrics (include `source` and `category` from the frontmatter):
   ```
   node ${CLAUDE_PLUGIN_ROOT}/scripts/append-metrics.js .claude-code-hermit/state/proposal-metrics.jsonl '{"ts":"<now ISO>","type":"created","proposal_id":"PROP-NNN-slug-HHMMSS","source":"manual","category":"improvement"}'
   ```
5. Update state summary:
   ```
   node ${CLAUDE_PLUGIN_ROOT}/scripts/generate-summary.js .claude-code-hermit/state/
   ```

## Do NOT Create Proposals For

- Trivial fixes — just fix them directly
- Style preferences — put those in `OPERATOR.md`
- Things that auto-memory already handles
- Hypothetical future needs — only real problems observed during work
- **Mirroring `config.json` into OPERATOR.md** — propose a `/claude-code-hermit:hermit-settings` change instead. Operator-editable prose is for things `config.json` can't express (focus, constraints, approval gates, comms style). Routine schedules, channel IDs, `permission_mode`, `agent_name`, `sign_off`, `escalation`, and `idle_behavior` are loaded structurally — duplicating them into OPERATOR.md is a token tax that drifts when config changes.

## Capability Proposals

If the proposal affects security boundaries — permissions, network access, credential handling — clearly note the security impact so the operator can make an informed decision.

When your operational scope changes (new API, new local service, new publishing channel), create a PROP recommending deny pattern additions or networking changes. Never modify `deny-patterns.json` or Docker config directly. The operator implements security changes.

When the proposed solution involves creating a new agent, skill, heartbeat item, or OPERATOR.md change, think hard and make the Suggested Plan self-contained:

**For a new sub-agent:**
1. Create `.claude/agents/<name>.md` with:
   - Frontmatter: name, description, model (match to complexity — haiku for scanning, sonnet for reasoning), maxTurns, tools, disallowedTools, memory (project for shared team knowledge, user for personal cross-project knowledge)
   - System prompt: role, constraints from OPERATOR.md, output format
2. Test by delegating a representative task to the agent
3. Verify it produces correct output and respects constraints

**For a new skill:**
1. Create `.claude/skills/<name>/SKILL.md` with:
   - Frontmatter: name, description
   - Numbered steps covering the full workflow
2. Test by invoking the skill with a representative input
3. Verify it completes correctly

**For a heartbeat check:**
1. Add the check to `.claude-code-hermit/HEARTBEAT.md` under the appropriate group
2. Run `/claude-code-hermit:heartbeat run` to verify it evaluates correctly

**For an OPERATOR.md refinement:**
1. Present the suggested addition to the operator
2. The operator decides where and how to add it — the agent never modifies OPERATOR.md directly