bettersense

Use for a periodic (quarterly / annual) career retrospective across the ENTIRE bettersense memory — producing a longitudinal self-assessment with cited growth deltas since the last retro and the honest gaps to work on next. Trigger phrases include "run my career retro", "where am I in my career", "annual self-assessment", "how have I grown this year", "it's review season, take stock of everything". Reads wins, all stakeholder reflections, self-reflections, pulses, and charters; writes a dated retro to self/retros/ so the next one can measure change. Distinct from wins-curate (which builds one audience-facing artifact like a promo packet) and self-reflect (a single in-the-moment entry). The meta-synthesis whose output compounds over years.

Use when the user needs a decision or backing from executives and is preparing the meeting or memo that gets it — QBRs, roadmap reviews, headcount asks, architecture investment pitches, "I'm presenting to the VP/C-suite next week". Trigger phrases include "prep my exec readout", "I'm presenting to leadership", "I need sign-off from the VP", "help me get this decision approved". Managing up at the decision moment: audience power map, the explicit ask, pre-wiring, and objection handling. Distinct from demo-prep (performing a product) and the-status-crafter (the recurring update rhythm). Reads your stakeholder reflections on the execs in the room.

Use when a new model version ships (or a current one is deprecated) and the user must decide whether and how to migrate a LIVE AI feature — "Claude X just came out, should we move?", "our model is being deprecated in 90 days", "the new model is cheaper, can we switch?", "plan the migration to [model]". Runs the checklist: inventory what's pinned to the old model, re-run evals before believing anything, revisit decision-log entries tied to the old version, re-baseline cost and latency, stage the rollout with rollback criteria. Distinct from ai-pm-frameworks (choosing a model for a NEW feature) and the-vendor-evaluator (choosing a provider).

Use to set up or work with a SHARED, git-backed team workspace for artifacts a team co-owns — team charters, strategy docs, decision records — kept strictly separate from your private reflections, which never leave your machine. Trigger phrases include "share our team charter with the team", "set up a shared bettersense workspace", "put our strategy doc in the team repo", "how do teams use bettersense together". Establishes `$BETTERSENSE_TEAM_HOME` (a separate git repo), enforces a hard wall that personal files (reflections, wins, retros, commitments) are NEVER shared, and drafts the branch/commit/PR — but never pushes or opens a PR for you. The multiplayer layer with the privacy wall built in.

Use when a senior IC (staff/principal engineer, architect, tech lead) needs to write a technical strategy or direction doc — where a system or domain should go over 12–24 months and why. Trigger phrases include "write a tech strategy for [domain]", "I need a technical direction doc", "our platform needs a north star doc", "help me write the tech vision for [area]". The staff+ artifact: turning engineering judgment into direction others can follow without you in the room. Distinct from strategy-doc (its product/business peer) and the-rfc-reviewer (reviewing one proposal). Saves to strategy/tech-<area>.md.

Use when the user's work is better than their visibility — building deliberate, non-gross sponsor awareness so the right people know what they do before the promo/calibration moment. Trigger phrases include "nobody knows what I do", "how do I get more visibility", "I need a sponsor", "my work speaks for itself but nobody's listening", "I was passed over because people don't know me", "how do I self-promote without being obnoxious". The ongoing drip between formal moments: who needs to know, what they should know, and amplification that reads as communication, not bragging. Distinct from wins-curate (assembles the formal packet); reads wins.md for what's worth amplifying.

Use to log something from the current conversation into the user's bettersense memory without re-typing it — a decision that just got made, a win that surfaced mid-discussion, an observation about a stakeholder, a self-insight. Trigger phrases include "log this", "capture this", "save that decision", "add that to my wins", "put that in my reflections", "remember this", or when a substantive conversation just concluded and its outcome would otherwise evaporate. Distinct from decision-log / wins-log / stakeholder-reflect / self-reflect invoked directly (blank-page capture): this skill drafts the entry FROM the conversation that just happened, shows it, and files it in the right place after approval.

Use to track what the user has promised — to their manager, execs, partner teams — and to keep those promises from silently going stale. Trigger phrases include "what have I committed to", "add a commitment", "I promised X by Friday", "am I overcommitted", "help me say no to this", "I need to renegotiate a deadline". Maintains a lightweight ledger at ~/bettersense-work-reflections/commitments.md: log promises when made, review what's due or slipping, renegotiate early with a script, and pressure-test new asks before saying yes. Distinct from wins-log (what you did) — this is what you owe. The saying-no support treats capacity as a trade-off conversation, not an apology.

Use when the user is preparing for a demo — exec review, customer pitch, board update, investor meeting, sales call, or all-hands. Trigger phrases include "I'm demoing X tomorrow", "help me prep for the review", "what could go wrong in this demo?". Especially valuable for AI-feature demos, where probabilistic systems can fail in ways scripted demos can't predict.

Use to health-check the user's bettersense memory directory — validate the file layout, catch problems before they cost data, and set up backups. Trigger phrases include "run bettersense doctor", "check my reflection files", "is my bettersense data okay", "something seems off with my stakeholder files", "back up my reflections", "I'm moving to a new machine". Validates ~/bettersense-work-reflections/ (or $BETTERSENSE_WORK_REFLECTIONS_HOME): stakeholders.json integrity, orphaned or unregistered stakeholder files, layout drift, and backup status. Read-only by default — proposes fixes and applies them only with explicit approval per fix.

Use when an EM wants to assess how well their engineering systems and processes are working — not team morale or people dynamics (that's team-diagnosis), but the productivity layer: are the right things being measured, where is developer experience breaking down, is onboarding a signal of deeper friction, and how to make the case for platform investment. Trigger phrases include "is my team actually productive", "I want to understand developer experience on my team", "how do I measure engineering productivity", "I need to justify platform team investment", "our onboarding is too slow".

Use when the user is preparing to give feedback to a teammate, direct report, peer, or stakeholder — performance reviews, 1:1 prep, post-incident conversations, peer reviews, 360s, written async feedback, or any moment they're drafting "how do I tell them that…". Apply the COIN structure to compose the message and the SOLID checklist to pressure-test it before delivery.

Use when a PM or team wants to stress-test whether their work is actually connected to something the business cares about. Runs before strategy-doc or prioritization-frameworks — it answers "are we even pointed at the right thing?" Trigger phrases include "are we doing the right work?", "I'm worried my team isn't driving real impact", "help me check if my team is aligned", "I'm worried about layoffs", or any moment of doubt about whether the team's work would survive scrutiny.

Use when the user is preparing for a 1:1 — as a manager preparing to meet with a report, as an IC preparing to meet with their manager, or as a peer preparing for a regular sync. Trigger phrases include "I have a 1:1 with X tomorrow", "help me prep for my 1:1", "what should I bring up in my next 1:1?". Builds an agenda matched to the relationship and the moment, not a generic template. If the other person is a registered stakeholder, reads their reflection file first so the agenda carries what the user already knows — open loops, recent observations, questions worth asking.

Use to surface unsolicited patterns the user hasn't explicitly asked about — across stakeholder reflections, wins log, self-reflect entries, and (eventually) pulse reports. Trigger phrases include "what patterns am I missing", "anything notable across my files", "scan my reflections for things I should know", "weekly cross-cutting check". Designed to be invoked on demand or fired on a weekly Desktop scheduled task (not cloud routines — those cannot access local files). Distinct from `stakeholder-synthesize` (user-driven, scoped to one person/category) — this is unsolicited, cross-cutting, and surfaces what the user hasn't thought to look at. Citation-disciplined: every pattern claim cites specific dated entries.

Use when the user is dealing with underperformance, considering a PIP, navigating a brilliant-jerk pattern, documenting concerns, or preparing for a hard performance conversation. Trigger phrases include "I have a report who's underperforming", "should I PIP X", "I need to document this", "how do I have the hard conversation", "I'm worried about [report]'s trajectory". The hardest skill in management — most managers avoid it for too long, then escalate badly. This skill helps the user move through the ladder deliberately: coaching → formal feedback → improvement plan → termination, with documentation and humanity at each stage.

Use for pre-mortem analysis of decisions, projects, or initiatives — solo and lightweight, or facilitated with a team before a launch or strategic commitment. Trigger when the user says "what could go wrong", "risk assessment", "pre-mortem this", "let's run a pre-mortem", or when evaluating risks for a plan. Applies a three-category framework (Critical, Perceived, Undiscussed risks) and, for team sessions, a facilitation flow that ends in an action plan with owners — not a brainstorm that ends in anxiety.

Use when the user wants to know which stakeholder reflections are overdue. Trigger phrases include "what's due", "who haven't I thought about lately", "what's on my plate this week for stakeholder reflection", "stakeholder check-in", or any Monday-morning planning moment. Scans `~/bettersense-work-reflections/`, computes which question × stakeholder pairs are overdue based on `suggested_freq` and last entry date, and outputs a prioritized list. Designed to be invoked on demand or fired on a weekly Desktop scheduled task (not cloud routines — those cannot access local files).

Use when the user is new to bettersense and doesn't know where to begin, or when they want a tour of what's available. Trigger phrases include "where do I start", "how do I use this", "what can you do", "what should I run first", "I just installed this", "help me get started", "what is bettersense", "how does this work", "I don't know what to do". Entry point for all new users.

Use for the user's recurring weekly review ritual — one guided session (~15 minutes) that wraps the whole bettersense maintenance loop. Trigger phrases include "run my weekly review", "Friday review", "weekly check-in", "start my week", "Monday planning", "/bettersense:weekly", or any "it's been a week, what should I catch up on" moment. Runs four time-boxed segments — wins capture, most-overdue stakeholder reflection, cross-cutting patterns, pulse glance — by composing wins-due, stakeholder-due, stakeholder-reflect, and patterns-watch. Distinct from the primitives it wraps: prefer this skill when the user wants the ritual; use the individual skills when they ask for exactly one piece.

Use when the user wants a low-pressure nudge on whether anything from the recent week is worth logging to their wins file. Trigger phrases include "what should I log this week", "is anything missing from my wins doc", "did I do anything notable this week", "Friday wins check". Designed to be invoked on demand or fired on a weekly Desktop scheduled task (not cloud routines — those cannot access local files). Probes by category (delivery / judgment / mentorship / recovery / range) because memory is selective and "anything notable?" alone surfaces nothing. Accepts "honestly, nothing this week" gracefully — the skill is for honest capture, not forced positivity.

Use when the user wants to coach someone — a report, peer, or mentee — through a problem rather than solve it for them. Trigger phrases include "coach me through how to talk to [report]", "I want to help [name] figure out X without telling them what to do", "let me practice a coaching conversation", "GROW conversation about [topic]". Flips the assistant into ask-not-tell mode: stays in question-mode for at least 5 turns, refuses to prescribe early, applies the GROW frame (Goal / Reality / Options / Will), and pushes back when *the user* tries to prescribe to their report instead of helping them work it out.

Use when the user wants to reflect on themselves as a leader — behavior under pressure, communication, time and energy, leadership style, fulfillment, advocating for themselves, calendar review. Trigger phrases include "let me reflect on myself", "self-check", "I want to think about how I've been leading lately", "self-reflection". Loads `~/bettersense-work-reflections/self/reflections.md`, picks 1–3 self-reflection questions appropriate to the moment, guides the reflection, and writes the dated entry back. Mirrors `stakeholder-reflect` but aimed at the user themselves.

Use when the user wants to reflect on a registered stakeholder — a manager, peer, direct report, or team — and capture the insight to a durable file. Trigger phrases include "let me reflect on John", "I want to think through my 1:1 with Jill", "log my thoughts on the Client Delivery ABC team", "reflect on [name]". Loads the stakeholder file, picks 1–3 questions appropriate to the moment based on cadence and what hasn't been touched recently, guides the reflection, and writes the dated entry back.

Use when the user wants to register a new stakeholder for ongoing reflection — a manager, peer, direct report, or team. Trigger phrases include "add a new stakeholder", "register Jill in managing-across", "I just got a new manager", "I'm now leading the X team", "let me set up reflection for [name]". Creates a persistent file at `~/bettersense-work-reflections/<category>/<slug>.md` that the `stakeholder-reflect`, `stakeholder-due`, and `stakeholder-synthesize` skills will use.

Use to create or update the user's anchor profile — a single private file (`~/bettersense-work-reflections/profile.md`) that captures who the user is, what they do, what context other skills need to know about them. Read automatically by other skills in the bundle when present, so the user doesn't re-explain themselves every session. Trigger phrases include "set up my profile", "create my user profile", "update my profile", "I changed roles, refresh my profile", "what does my profile look like". Inspired by the `SOUL.md` pattern from agents like Hermes — explain yourself once, get tailored output forever.

Use when a team lacks psychological safety — members don't speak up, withhold concerns, or fear making mistakes. Trigger phrases include "build psychological safety", "team is afraid to speak up", "create safe environment", "people are withholding their opinions", "no one challenges decisions", "fear-based culture". Provides concrete, actionable practices to build psychological safety, drawing from Amy Edmondson's research and Moussa's emphasis on trust-building conversations. Not just diagnostic (like team-diagnosis) but prescriptive — tells the leader exactly what to do this week.

Use when forming a new team, resetting an existing team after a reorg, or when a team's goals/roles/norms are unclear and causing friction. Trigger phrases include "create a team charter", "align our team on goals roles norms", "reset the team operating model", "new team kickoff", "team alignment workshop". Facilitates explicit conversation on the three foundations from Mario Moussa's 3X3 framework (Goals, Roles, Norms) and produces a living charter document stored at ~/bettersense-work-reflections/team-charters/<team-slug>.md. Especially useful for new product teams, new management layers, or after major org changes.

Use when a team needs to regularly revisit their Goals/Roles/Norms foundation to surface drift and realign. Trigger phrases include "team check-in", "are we still aligned", "team retro on our operating model", "review our team charter", "3X3 check-in". Facilitates a structured conversation (30–90 min) that answers: Are we still committed to our stated goals/roles/norms? If not, what's the gap and how do we close it? The second step of Moussa's 3X3 framework. Works from an existing team charter (from team-charter) or surfaces foundations de novo if none exist.

Use when a team has identified a gap between stated goals/roles/norms and actual behavior, and needs concrete, small-step action plans to close it. Trigger phrases include "close the saying-doing gap", "how do we actually change our behavior", "action plan for team norm change", "small steps to improve team work", "bridge the intention-behavior gap". The third step of Moussa's 3X3 framework: closes the gap between what the team says it wants to do and what it actually does, through targeted small steps with environmental support. Works best after a team-check-in or team-charter session that has surfaced specific gaps.

Use when a team is going through a transition — forming (new team), storming (conflict emergence), norming (establishing ways of working), performing (high function), or adjourning (team disbandment/transition). Also for resets after reorgs, new member integration, or when a team is stuck in a dysfunctional phase. Trigger phrases include "our team is changing", "new team member joining", "team reorg transition", "how do we reset our team", "team dissolving", "adjourning a team". Based on Tuckman's model applied to work teams with practical guidance for each phase. Complements team-charter, team-check-in, and stakeholder-manage.

Use when a team wants to understand and discuss their collective working style preferences — communication, decision-making, conflict, meeting effectiveness, and information sharing — to reduce friction and increase intentionality. Trigger phrases include "team work style assessment", "how does our team prefer to work together", "team style inventory", "understand our team dynamics", "communication preferences survey". Based on the insight from Moussa that team performance depends on paying attention to "how you talk to each other." Produces a shared understanding of the team's style profile, surface mismatches, and norms adjustments. Precedes or complements team-charter and team-check-in.

Use when the user wants to systematically identify, categorize, and quantify "glue work" (non-core technical activities like onboarding, documentation, unblocking, cross-team alignment, process improvement) on themselves or their team. Trigger phrases include "what glue work am I doing", "audit my glue work", "what non-promotable work is our team doing", "catalog our glue tasks", "how much time do we spend on glue", "map our glue work". Produces a structured inventory with time estimates, promotion-value assessment, and fairness analysis. Especially useful before promotion cycles, workload rebalancing, or role-transition decisions.

Use when managing engineers who naturally gravitate toward glue work (onboarding, documentation, unblocking, process improvement) and need protection from burnout, visibility for their impact, and career development that doesn't force them off the IC track. Trigger phrases include "my report does too much glue", "how do I protect my glue person", "glue worker promotion", "coaching someone who's always helping others", "my engineer is drowning in non-promotable work". Provides manager-specific guidance on credit amplification, workload rebalancing, promotion advocacy, and skill development that preserves technical growth.

Use when an engineer who does significant glue work (onboarding, documentation, unblocking, cross-team alignment, process improvement) needs to build a promotion packet that frames that work as technical leadership. Trigger phrases include "promotion case for glue work", "I do a lot of glue work how do I get promoted", "frame my non-code work for promotion", "my manager says I need more technical accomplishments", "I'm a glue person how do I get senior". Works alongside or as a specialized mode of `report-promo-case`. Produces a promotion-ready narrative that translates glue tasks into ladder-appropriate evidence, with artifact collection guidance and manager talking points.

Use when the user wants to analyze whether non-promotable (glue) work is fairly distributed across their team, with attention to demographic and seniority patterns. Trigger phrases include "is our glue work fair", "who does the non-promotable work on our team", "audit workload distribution", "are women doing more glue work", "workload equity analysis", "non-promotable work allocation". Produces a fairness diagnosis with evidence, bias signals, and concrete redistribution recommendations. Manager-facing skill with sensitivity to privacy and psychological safety.

Use to produce a single-page dated pulse report on product health — usage metrics, system performance, AI-feature signals (hallucination, refusal, eval drift), counter-metrics, and follow-up investigation. Trigger phrases include "run a pulse on [area]", "give me a product health snapshot", "weekly product pulse", "what does the data say this week". Reads strategy.md to know what to watch and which counter-metrics matter. Saves to `~/bettersense-work-reflections/pulses/<area-slug>/pulse-YYYY-MM-DD.md` so the folder accumulates into product memory over time. Designed for daily/weekly Desktop scheduled tasks (not cloud routines — those cannot read or write local files). Privacy-first — defaults to aggregated/redacted data; surfaces provenance.

Use when scoping AI features, deciding build-vs-buy-vs-rule, designing eval harnesses, choosing models for cost/latency trade-offs, or planning guardrails for LLM-based products. Trigger when the user is doing AI product management work — feasibility, architecture, or reliability decisions for probabilistic systems.

Use when the user wants a structured read on the *health* of their team — beyond individual morale to delivery cadence, attrition risk, dependency tax, on-call burden, peer relationships, and cross-cutting patterns. Trigger phrases include "how is my team doing", "I want a team health check", "diagnose my team", "before my skip-level update, what should I flag", "is something off with the team that I'm missing". Reads the user's stakeholder-reflect entries on direct reports + team file + any inputs the user provides (recent retros, attrition events, eng survey scores), and produces a multi-dimensional diagnosis with patterns, risks, and concrete actions.

Use when the user is designing the metric tree for a feature (especially an AI feature) — picking a north star, leading and lagging indicators, quality metrics, and counter-metrics. Trigger phrases include "what should we measure for…", "how do we know if this is working?", "I need to define success for…", or any spec where the success metrics section is fuzzy. Distinct from `the-eval-designer`, which measures model quality; this skill measures business success and guards against optimizing the model into a worse product.