Skip to main content

insight

Captures a developer's POC observation — "X is missing", "we could change Y", "this feels off" — as a one-line row in the POC Insights log, without touching docs/proposals/. The whole point is low friction: get the thought recorded in seconds so it isn't lost, and let the every-2-3-days review decide whether it becomes a real artifact.

This is the lightest capture surface on the platform. It is not draft-proposal (a worked idea for triage), not propose-team-rule (a generic rule → PR), and not the Open Questions register (a decision needing an answer). If the developer already has a worked proposal or a clear decision-to-make, route them there instead.

When to invoke​

  • /insight, or the developer voices an observation during the build: "we're missing X", "we could change Y", "why isn't there a Z", "this should probably be different", Hebrew "יש לי תובנה", "חסר לנו", "אפשר לשנות".
  • Do not invoke for: a fully-worked feature idea (→ /propose), a generic coding/workflow rule (→ /share-rule), a decision that needs a human answer now (→ the Open Questions register), or actual bug/task work (→ ClickUp//breakdown).

Steps​

  1. Capture the observation in one line. What's missing or could change, in the developer's words. If it's vague, ask one clarifying question — but keep it light; an insight is a seed, not a spec.
  2. Classify the area — which surface/agent/domain it touches (e.g. agents, frontend, CI, docs, taxonomy).
  3. Locate the platform repo ($BEWITH_DIR) per session-safety.md. Worktree-isolate (never touch the developer's working tree): 
    BRANCH="docs/insight-<short-slug>"          # `insight/` is NOT an allowed branch type — branch-name-check rejects it
    WORKTREE="$(mktemp -d -t bewith-insight.XXXXXXXX)"
    git -C "$BEWITH_DIR" worktree add -b "$BRANCH" "$WORKTREE" origin/master
    # The commit triggers the pre-commit hook, whose validators import js-yaml etc.;
    # a fresh worktree has no node_modules, so symlink the main checkout's to avoid ERR_MODULE_NOT_FOUND.
    ln -s "$BEWITH_DIR/node_modules" "$WORKTREE/node_modules"
  4. Append a row to docs/insights/index.md — next INS-N id, the insight, area, raised-by (the git user / current developer), date (ask for it or use the session date — do not invent), status open, outcome empty.
  5. Commit + push + open a PR titled insight: <short>; body = the one-liner + area + who. Keep it tiny. Do not create anything under docs/proposals/.
  6. Cleanup the worktree (git worktree remove --force).
  7. Tell the developer it's logged and will be triaged at the next 2-3 day review.

Anti-patterns​

  • Turning an insight into a proposal. If it's worth a worked proposal, that's /propose — but the default is: capture light, discuss later. Don't pre-empt the review.
  • Touching docs/proposals/. Insights live in docs/insights/ only. Keeping proposals clean is the reason this skill exists.
  • Editing the developer's working tree. Always worktree-isolate.
  • Inventing the date or author. Use the real git user + the session date; ask if unsure.

Cross-references​