Skip to main content

Draft proposal

This skill takes an idea the developer wants to capture and turns it into a markdown file under docs/proposals/ in bewith-dev/bewith-docs. The proposal lands directly on master (or as a PR — the developer chooses) so the team can find it next time they triage.

Different from propose-team-rule. That skill is for generic team conventions / coding rules. This skill is for feature, infrastructure, process, or tooling ideas — things that get implemented as side projects.

When to invoke​

Manual entry point: /propose [optional one-line description].

Auto-invoke (after explicit user approval): if a developer mentions an idea during a session that's clearly a feature/infra change rather than a team rule, you can offer to capture it:

"זה נשמע כמו רעיון שווה ליישום. רוצה שאדריקבע פרופוזל ב-bewith-docs?"

If they confirm, invoke this skill. If they say "this is just a thought, not yet" — drop it. Each proposal consumes a little triage attention later.

Proposal vs team rule vs RFC — fast triage​

TypeUse whenWhere
Team rule (/share-rule)Generic convention, coding standard, gotcha that applies broadly.claude/rules/team/
Proposal (/propose)Feature/infra/process idea, side-project-sized (S/M effort)docs/proposals/
RFC (manual, no skill yet)Multi-team, week-plus, contract-changingdocs/rfcs/

If unsure, default to proposal — it's the lightest tier and graduates naturally.

Steps​

1. Confirm the idea with the developer​

Restate what you're about to capture, in one or two sentences. Get explicit confirmation. Example:

"אני הולך לפתוח פרופוזל: 'BE interceptor שמתייג Datadog logs ב-app.version מה-X-App-Version header'. category: infrastructure, effort: S. ברירת מחדל owner: null (status: open) — אם אתה רוצה לקלום ולהוביל, תגיד לי. מאשר?"

If the developer wants to wordsmith, edit together before the file is written. Once approved:

2. Collect the four required fields​

You need answers to draft a complete proposal. Ask whichever the developer didn't already provide:

  1. Problem — what's the pain or opportunity? Push for concreteness (a specific scenario, an incident, a metric) — reject vague "it would be nice if".
  2. Sketch of approach — bullet points enough to picture the work. Not a design.
  3. Effort — S (under a day), M (1-3 days), or L (more than 3 days, consider RFC instead).
  4. Owner — default is owner: null and status: open. Only set owner to the author (and status: claimed) if they explicitly say "I'll drive this" or "claim it". Don't assume — most proposals are surfaced for triage to pick up an owner, not pre-claimed by the author. When in doubt, ask: "Are you claiming this to drive yourself, or leaving it open for triage?"

The other frontmatter fields you fill in automatically:

  • id, created, author from context
  • category you infer from the description (infrastructure / feature / process / tooling)
  • status: open (the default) — or claimed only if the author explicitly claimed
  • triaged: null, clickup_id: null, graduated_to: null, related: [], tags: []

3. Audit existing proposals to spot clusters​

Before drafting, grep the existing proposals for overlap:

grep -rn "<key-phrase>" "$BEWITH_DIR/docs/proposals/" 2>/dev/null

If a proposal on the same topic exists:

  • If it's claimed / open / triaged — surface it to the developer. They can edit it, link the two via related:, or decide to skip the new one.
  • If it's archived — note the prior rationale to the developer. Maybe their new idea overcomes the original objection; maybe not.

Don't auto-merge. Just inform.

4. Locate the bewith-docs checkout​

Follow the canonical resolution cascade in docs/methodology/session-safety.md — "Locating the bewith-docs checkout". Set BEWITH_DIR=<resolved path> and continue.

The cascade lives in one place so all state-mutating skills inherit any future change. Do not restate it here.

5. Pre-flight safety checks​

# 5a. Generate the proposal slug
TODAY="$(date -u +%Y-%m-%d)"
SLUG="proposal-${TODAY}-<kebab-case-title>"
BRANCH="proposal/${SLUG}"

# 5b. Refuse if the file or branch already exists
if [ -f "$BEWITH_DIR/docs/proposals/${SLUG}.md" ]; then
  echo "ERROR: $BEWITH_DIR/docs/proposals/${SLUG}.md already exists. Pick a different slug or edit the existing file." >&2
  exit 1
fi

git -C "$BEWITH_DIR" fetch origin master --quiet
if git -C "$BEWITH_DIR" rev-parse --verify --quiet "refs/heads/${BRANCH}" >/dev/null; then
  echo "ERROR: branch ${BRANCH} already exists locally." >&2
  exit 1
fi
if git -C "$BEWITH_DIR" ls-remote --exit-code origin "${BRANCH}" >/dev/null 2>&1; then
  echo "ERROR: branch ${BRANCH} already exists on remote — probably an in-flight proposal." >&2
  exit 1
fi

6. Create an isolated worktree​

Never operate on the developer's working tree. Concurrent sessions may be editing it.

WORKTREE="$(mktemp -d -t bewith-proposal.XXXXXXXX)"
git -C "$BEWITH_DIR" worktree add -b "${BRANCH}" "${WORKTREE}" origin/master
# Pre-commit validators import js-yaml etc.; a fresh worktree has no node_modules.
ln -s "$BEWITH_DIR/node_modules" "${WORKTREE}/node_modules"

7. Draft the proposal file​

Use the template at docs/templates/proposal.md as the structural reference. Write to ${WORKTREE}/docs/proposals/${SLUG}.md with this frontmatter shape (fill in the values you collected in step 2):

---
id: <slug>
title: "<short title>"
description: "<one-sentence summary>"

status: open                 # default; use 'claimed' only if author explicitly claimed
author: "<git user.name or @handle>"
owner: null                  # default; set to author only if explicitly claimed
created: <TODAY>
triaged: null
category: <infrastructure | feature | process | tooling | other>
effort: <S | M | L>

related: []
clickup_id: null
graduated_to: null

tags: []
---

Body sections in order:

  1. Title (H1 — same as title)
  2. Badges row (one each for status, author, owner, effort)
  3. Problem — the pain or opportunity
  4. Proposal — the idea (1-2 paragraphs)
  5. Why now / Why us — motivation
  6. Sketch of approach — bullets
  7. Open questions — bullets
  8. Related — links to specs, RFCs, ClickUp tickets
  9. Triage notes (empty stub for now)

Match the seed example at docs/proposals/proposal-2026-05-29-be-datadog-tagging-from-app-version.md for tone and structure.

8. Append a row to the proposals index​

Edit ${WORKTREE}/docs/proposals/index.md and add a row to the Active table:

| [<title>](./<slug>) | <author> | <owner or _open_> | <category> | <effort> | <status> |

Keep rows ordered by created (newest at top). Do not auto-generate the index from frontmatter — that's a future enhancement; for now the file is hand-maintained.

9. Commit, push, and (optionally) open a PR​

git -C "${WORKTREE}" add docs/proposals/${SLUG}.md docs/proposals/index.md
git -C "${WORKTREE}" commit -m "$(cat <<EOF
proposal: <short title>

<one-paragraph summary — same as the description field plus a sentence
on why it's being proposed.>

Author: <author>
Owner: <owner or unassigned>
Category: <category>
Effort: <effort>

Refs: bewith-dev/bewith-docs docs/proposals/
EOF
)"

git -C "${WORKTREE}" push -u origin "${BRANCH}"

Then ask the developer:

"Open a PR for team visibility, or just merge directly to master (proposal tier is low-bar)?"

  • PR: gh pr create --repo bewith-dev/bewith-docs --base master --head ${BRANCH} --title "proposal: <title>" --body "<short body>"
  • Direct merge: gh pr create ... --label "proposal" && gh pr merge --squash --auto (or fast-forward if the developer prefers).

Surface the resulting URL.

10. Clean up the worktree​

git -C "$BEWITH_DIR" worktree remove "${WORKTREE}" --force

Always run this, even on failure paths (use a trap).

Failure modes — explicit list​

  • No bewith-docs clone → stop. Tell the developer. Do not invent fallbacks.
  • Branch / file already exists → stop. Tell the developer the slug clashed; let them rename.
  • gh CLI not authenticated → tell the developer to run gh auth login and retry. Don't push without a PR/merge follow-up.
  • No git user.name configured → ask the developer for their handle and pass it as --author to the commit; don't fail silently.

What this skill does NOT do​

  • It does NOT create a ClickUp task. That happens during triage.
  • It does NOT open Slack discussions. The PR or commit on master is the discoverable artifact.
  • It does NOT enforce any review window. Proposals are low-bar — discussion happens in PR comments if anyone wants, otherwise the proposal waits for triage.
  • It does NOT validate that the idea is "worth doing". That's what triage is for.