POC Insights
A low-friction log for the "what's missing / what we could change" observations that surface while building the POC — kept separate from Proposals on purpose. The goal: anyone can dump an insight in seconds, we discuss them together every 2-3 days, and only the agreed ones graduate to a real artifact. Nobody injects a unilateral change; proposals stay clean.
Why this exists (and how it differs)
| Surface | For | Weight |
|---|---|---|
| Insights (here) | "I noticed X is missing / we could change Y" during the build | Lightest — a one-line observation |
Open Questions (docs/open-questions.md) | A decision that needs a human answer | Light — a tracked question |
| Proposals | A worked feature/infra/process idea for triage | Medium — a written proposal |
| ADRs / Decisions | A decision that has been made | Durable record |
| ClickUp task | Agreed, scheduled work | Execution |
An insight is not a proposal and not a commitment to change. It is a captured thought. The 2-3 day review is where insights become (or don't become) one of the heavier artifacts above.
How to add one
Use the insight skill / /insight command (or add a row by hand). It captures: what you noticed, the area, who raised it, the date, and status open. It does not touch docs/proposals/.
The review ritual (every 2-3 days)
Walk the open insights together:
- Promote — agreed + worth doing → open a Proposal, an ADR/Decision, an Open Question, or a ClickUp task. Mark the insight
promotedwith a link. - Park — interesting, not now → leave
openwith a note. - Drop — not pursuing →
droppedwith a one-line reason.
Resolved rows stay (struck context) so the thinking is visible. Keep the open list short — a growing pile of un-triaged insights is the smell this ritual prevents.
Insights log
| # | Insight (what's missing / could change) | Area | Raised by | Date | Status | Outcome / link |
|---|---|---|---|---|---|---|
| INS-1 | Institutionalize efficiency/cost discipline — priority quality > speed > cost. "Code before model": a deterministic step is a script the AI invokes (fixed, parameterized, results tracked), not something the model reasons through. Plus trim recurring per-session context injections, keep agent/skill bodies lean, and tier models (Haiku mechanical / Opus judgment). Promote to a short methodology section + a new-artifact "can this be deterministic?" gate + an efficiency lens in code-reviewer; apply now to WS4 ranking + WS5 aggregation. Never at the expense of output quality. | methodology / governance | relbns | 2026-06-06 | promoted | docs/methodology/context-and-cost-economy.md + delegate-heavy-context skill + playwright-snapshot-warn hook (PR #277). Gates (new-artifact + code-reviewer) deferred to a follow-up. |
| INS-2 | Move the bewith plugin to always-latest so teammates install once and never manually update. marketplace.json source:"./" is already portable — works as a local-dir marketplace (Ariel's dev) AND a github one (teammates: claude plugin marketplace add bewith-dev/bewith-docs + install bewith@bewith-dev). Claude Code has no auto-update toggle — it's version resolution: an explicit version (today 0.1.1) PINS; omitting version → commit SHA becomes the version → every master commit auto-ships at startup (github sources only; private repo needs GITHUB_TOKEN). Ariel wants BOTH a unified bewith update (CLI+plugin in one cmd) AND startup auto-latest. Reverses PR #157's explicit-version + claude plugin tag model. TRADE-OFF: zero-touch latest vs every commit instantly hitting all teammates (no release gating — OK while no real users; revisit with staged gating). Build after PR #158 + the consumption-model/governance.lock PR. | infra / plugin | relbns | 2026-06-08 | adopted | Implemented: dropped version from plugin.json + marketplace.json (+ removed root VERSION) → SHA-versioned always-latest. Startup auto-update on the private repo needs GITHUB_TOKEN/GH_TOKEN. No release gating (gate via a pinned marketplace ref if needed later). |
| INS-3 | Enrich the /sessions HTML dashboard so it answers "what is my open branch's status, and what am I working on in parallel?" — the gap that leaves a developer feeling stuck. Today scripts/sessions-view.mjs renders only live sessions (title, surface, branch, age, state, collision flag, resume); it does not show PR number/state (open/draft/merged), CI status (pass/fail/pending), ahead/behind vs master (the baseline_origin_master is already recorded by session-register.sh but never displayed), and there is no inventory of branches that have an open PR but no live session ("the branch I forgot about"). Proposal: (1) PR column (PR# + state + CI) from a cached, deterministic gh pr list/gh pr view --json call — code-before-model ([[INS-1]]), a script not model reasoning, fail-open if gh is unavailable; (2) ahead/behind-master column from git rev-list --count against the recorded baseline; (3) a "branches with an open PR but no live session" section so forgotten branches surface. Scope = sessions-view.mjs + a small best-effort gh/git layer (also benefits SwiftBar + --json). Build deferred to after the R&D talk (Ariel's call); spec captured now. | sessions / mission-control | relbns | 2026-06-11 | open | — |