Product Role Details Research — PM, UX & Engineering Skills

Comprehensive research on product team role capabilities and AI-assisted skill commands. Source: /Users/parhumm/Projects/jaan-to/website/.claude/roles-details-research.md Added: 2026-02-01

Product Management (PM/PO) • Customer problem discovery — interviews, observation, pain capture Key Points: Product discovery focuses on identifying real customer needs and pain points. Common techniques include one-on-one customer interviews (to hear users’ experiences firsthand and find their pain points) and field observations of users in their environment . During interviews, avoid pitching solutions; instead, ask open-ended questions and listen actively to uncover frustrations . Observing users or analyzing their workflows can reveal unarticulated needs . The goal is to capture the core pains users face and validate that these are meaningful problems worth solving . By deeply understanding what the problem is and why it matters to the customer, you ensure the product will tackle a real issue (and not just an assumed one). • /pm-discovery:interview-guide [persona] [topic] — outputs a 30-min script + hypotheses checklist Key Points: Preparing a structured interview guide helps keep customer interviews unbiased and focused. Start with a consent and introduction to build trust, then prompt the interviewee to share a story of their recent experience related to the topic . A good 30-minute interview might include: brief intros and context setting (1-2 min), a very short overview of your concept (if needed) (2-3 min), then ~25 minutes of open-ended Q&A . Design your questions to test your hypotheses about user needs – for example, if you hypothesize users struggle with a certain step, ask them to describe the last time they did that and listen for pain points . Avoid leading questions; use open-ended ones (“Tell me about the last time you…”) to get genuine insights . Include a checklist of assumptions (hypotheses) you want to validate, such as “Users find feature X hard to use” or “Users have no workaround for Y”, and ensure your script touches on each. Ultimately, the guide should lead users through their story (context), the problems they encountered, how they tried to solve them (existing alternatives), and the outcomes . This approach yields concrete evidence (notes, quotes) either supporting or refuting your team’s hypotheses about user needs. • /pm-discovery:insights-synthesis [notes] — outputs top pains, quotes, frequency table Key Points: After conducting user interviews or research, synthesize the raw notes into actionable insights. First, review and code the notes – highlight key data points (each distinct thought or observation) and tag them (e.g., pain point, need, quote) . Group similar points to identify recurring themes or pains (often done via affinity mapping or a spreadsheet). For each major pain point or user need, list how many users mentioned it (frequency) to gauge prevalence . Pull out compelling direct quotes from users that illustrate each pain point – quotes give color and credibility to the insights (e.g., “I tried to do X, but it was so frustrating that I gave up”). Summarize the top pains (the most frequent or severe problems users have) and any notable gains they desire. Present the findings with a simple frequency table or tally (e.g., Pain A – mentioned by 4/5 users; Pain B – 3/5 users) to make it clear which problems are most common . This synthesis turns messy notes into a clear set of validated user problems, supported by evidence, which will inform your product’s problem statements and priorities. • /pm-discovery:problem-statement [insights] — outputs 1–3 crisp problem statements + non-goals Key Points: Using the research insights, craft a problem statement that succinctly describes each core problem you intend to solve. A strong problem statement focuses on what the problem is, who it affects, and why it’s important . For example: “Busy parents (who) struggle to find healthy dinner options (what problem) due to lack of time for meal planning, leading to unhealthy eating and stress (why it matters).” Keep it simple and specific, avoiding implying any solution. Include context about when or why the problem occurs and the impact if it’s not solved. Also define the scope and non-goals for each problem: explicitly state what you won’t address . For instance, you might clarify that your solution will focus on planning recipes (scope) but not on grocery delivery (non-goal) . Listing non-goals prevents scope creep and makes sure everyone understands the boundaries of the solution. Aim to write 1–3 of these crisp problem statements that capture the top pain points from your research – these will serve as a “north star” for ideation and keep the team aligned on what problem we’re solving and why, without jumping to how. Each statement should be testable (measurable) later, tying back to real customer evidence. • Market + competitor scan — map alternatives and gaps Key Points: Before designing a solution, analyze the market landscape and existing alternatives. Identify both direct competitors (those offering very similar products) and indirect competitors or workarounds (other ways users solve the same problem) . Map these alternatives to see where each stands – for example, you might create a competitor matrix plotting key factors (price, feature richness, target segment, etc.) . This helps reveal market gaps: underserved segments or unmet needs not addressed by current solutions . Look for areas where few competitors operate or where user needs are only partially met – those gaps represent opportunities. Also, compare competitors side-by-side on important criteria (feature list, usability, customer ratings, etc.): create a table of competitors vs. criteria and mark who offers what . This highlights where your product can differentiate (e.g., a feature all users want but no current competitor provides). The scan should result in an understanding of what alternatives customers have today, each competitor’s strengths/weaknesses, and any white space in the market your product could exploit . Knowing the market context ensures your product positioning and feature set are informed by real competitive insight, not done in a vacuum. • /pm-market:competitor-matrix [competitors] [criteria] — outputs comparison table + gaps Key Points: A competitor matrix is a structured comparison of competitors against key criteria. To create one, list your top competitors (including status quo or DIY solutions) and the features or factors you want to compare (for example: pricing, key features, platform support, usability, etc.) . Fill in the table by checking which competitor offers which features, and how well (e.g., ✔ = has feature, ✘ = missing). This visual makes it easy to spot gaps – criteria where few or no competitors deliver well . For instance, you might find that none of the existing apps offer an integrated collaboration feature – a gap your product could fill. You can also include qualitative criteria like target audience or positioning to see how they differ. The matrix should be accompanied by a brief analysis of each gap or differentiator: “Only 1 out of 5 competitors offers offline access, and users complain about it – potential differentiator for us.” This deliverable concisely shows where each competitor stands and highlights opportunities for your product’s strategy. It informs both product decisions (what to build) and messaging (what to emphasize as your unique strengths). • /pm-market:positioning-brief [product] [audience] — outputs positioning, differentiators, risks Key Points: A positioning brief defines how your product is uniquely valuable to a specific audience. It should clearly state who your target user is, what their unmet need is, and how your product fills that need better than alternatives . For example: “For freelance designers (target audience) who need to hand off assets efficiently (need), our product is a collaboration tool that provides real-time feedback and version control (positioning), unlike traditional email or folder sharing.” Highlight the top differentiators that set your product apart – these could be specific features, quality of service, price point, or a unique approach that competitors lack . Also candidly list potential risks or pitfalls in your positioning. These might include things like under-positioning (not communicating a clear benefit, so users don’t see anything special), or over-positioning (focusing too narrowly and missing a broader appeal) . Other risks: confused positioning (inconsistent messages causing user confusion) and doubtful positioning (claims that users find not credible) . By acknowledging these, you can take steps to avoid them (e.g., ensure your messaging is consistent and backed by evidence to avoid doubt). The positioning brief should end up as a succinct statement of your product’s value and uniqueness for the target market, plus a checklist of what to watch out for to keep that positioning strong. • Define target user — personas / JTBD, success criteria Key Points: Clearly defining the target user helps the team keep a user-centered focus. This often involves creating personas or using the Jobs-to-Be-Done lens. A persona is a fictional, yet research-based, profile representing a key user segment – including characteristics like their role or demographics, goals, and pain points. Focus on the persona’s top jobs, pains, and gains: what are they trying to accomplish (jobs), what frustrations or obstacles do they face (pains), and what benefits or outcomes they seek (gains) . For example, “Meet Alex, a busy marketing manager (persona). His job-to-be-done is compiling campaign reports. His pain points are time-consuming manual data exports, and his desired gain is a quick, one-click report.” Using JTBD (Jobs-To-Be-Done) mapping goes a step further by identifying the situation or trigger for the job and the outcome desired . In Alex’s case, the trigger might be end-of-month reporting time (he needs to gather data), and the desired outcome is a report ready without spending hours. Finally, define success criteria from the user’s perspective. Essentially, how will we know we’ve solved Alex’s problem? These should be measurable “done” criteria – e.g., “Alex can generate a report in <5 minutes (success = time saved by 90%).” Make sure success criteria are specific and testable (following the SMART principle: Specific, Measurable, Achievable, Relevant, Time-bound) . Solid personas or JTBD definitions paired with clear user-centric success metrics ensure the team designs the product to truly meet the target user’s needs and can verify when it does. • /pm-user:persona-card [segment] — outputs persona card + top jobs/pains/gains Key Points: A persona card is a one-page summary of a representative user. It typically includes a name (e.g., “Marketing Manager Mary”), a short bio or context (role, background), and most importantly the persona’s goals/jobs, pains, and gains. Use your research to fill these in: list the top jobs-to-be-done for that persona (what are they trying to achieve?), the primary pain points that hinder them (what’s frustrating or challenging in their current process?), and the key gains they desire (what outcome or benefit would delight them) . For example, Mary’s jobs might include “Publish weekly social media reports”; her pains could be “Data is scattered in many tools, takes 3+ hours to compile” and “Worries about accuracy”; her gains might be “Save time – wants reports in 30 mins” and “Impress boss with clear visuals”. Keep the content realistic and rooted in actual user quotes or data if possible. A good persona card also often shows a quote from the persona (“I just want a quick way to …”) to humanize them, and possibly their skill level or attitude (tech-savvy? budget-conscious?). The deliverable is a concise, easily digestible snapshot that team members can refer to and ask, “Would this solution really help Mary achieve her job and relieve her pains?” throughout development. • /pm-user:jtbd-map [use-case] — outputs JTBD + triggers + desired outcomes Key Points: A JTBD map for a use-case breaks down the job the user is trying to get done, the trigger or context that starts it, and the desired outcome the user expects. Start by articulating the Job-To-Be-Done in plain language, focusing on the user’s goal independent of any solution – e.g., “When [situation/trigger], the user wants to [job].” Next, identify the triggers: the events or circumstances that prompt the user to seek a solution. All jobs start with a trigger – it might be a problem (e.g., “it’s 12:00 and I’m hungry, so I need to find lunch”) or a specific situation (“quarter-end means I need to compile financials”) . These triggers frame the urgency and context for the job. Then specify the desired outcomes or benefits the user is seeking. In JTBD theory, outcomes can be functional (e.g., get a report done), emotional (feel confident about data), or social. For our example, the desired outcome of the lunch job might simply be “go from hungry to satisfied with minimal time” . Often it’s useful to list multiple outcomes: primary (the core need) and secondary (nice-to-haves). By mapping Trigger → Job → Outcome, you clarify why and when the user “hires” a solution. This map can also include current existing solutions the user uses, which indicates what you need to outperform. The result is a succinct narrative: “When [trigger], users need to [job], so that [outcome].” This ensures your team understands the context and success criteria for that use-case. • /pm-user:success-criteria [persona] [goal] — outputs measurable “done” criteria Key Points: Success criteria define what it means for the product or feature to successfully meet the user’s goal. They should be measurable conditions that, once met, signify the user’s problem is solved or the experience is acceptable . To set success criteria, revisit the persona’s goal and pains, and ask how you’ll know you’ve alleviated the pain. For example, if the persona’s goal is “upload a file to share with team” and their pain was “it takes too long”, a success criterion could be “File upload and share completed in <10 seconds on average.” If the goal is qualitative (like user understanding or satisfaction), try to quantify it via surveys or proxies (e.g., “90% of new users can complete onboarding without contacting support”). Good success criteria are essentially acceptance tests from a user perspective: they often start with “The user can… [do X under Y conditions].” They might also include error rates or satisfaction scores (e.g., NPS increases by 10 points for the workflow). Ensure each criterion ties to a metric or observable outcome (time, completion rate, error count, rating, etc.) so you can verify it. This might overlap with KPI definition, but at a feature level. By establishing these criteria up front, you give designers, engineers, and testers a clear target for “what good looks like” – and after release, you can measure against these to declare success or identify gaps to fix. • Problem statement — crisp, shared “what/why” Key Points: A problem statement is a concise summary of the problem your product or feature will address, and it’s crucial that the whole team and stakeholders share the same understanding of it. A good format is one sentence covering: the problem itself, the context or who is affected and when, and the impact or why it matters . For example: “Mobile users (who) drop off during onboarding (what’s happening), leading to a 30% lower Day-1 retention compared to desktop (impact) .” This one-liner tells us what’s wrong, for whom, and quantifies the pain. It’s specific and backed by data or observation (not a vague complaint) . Crafting such a statement often forces you to clarify terms and gather evidence (“Is it really 30% lower? Why mobile specifically?”), which is healthy. Once you have this crisp “what + why” problem statement, use it as a north star for ideation and as a sanity-check during development (“Is what we’re building actually solving this problem?”). It also aids communication – team members, executives, and even new hires can quickly grok the mission. Ensure the problem statement is prominently shared (in the PRD, kickoff decks, etc.). Additionally, alongside the statement, note any non-goals or scope constraints directly related – to reinforce what you are not solving here (preventing scope creep). In summary, invest time in getting a sharp problem definition; it aligns efforts and speeds up decisions by keeping everyone focused on the agreed “what” and “why” before jumping into “how.” • /pm-problem:one-liner [context] — outputs problem, impact, and who is affected Key Points: This is essentially asking for a one-sentence problem statement encapsulating the core issue. To deliver this, follow a formula like: Problem + Who/Context + Why it matters. For instance: “[User segment] are unable to [complete task], causing [quantified impact].” Make sure to include the who (user or customer segment) and/or context (“when doing X” or “under Y conditions”) , the specific problem or what’s happening, and a concrete consequence or impact of the problem if unresolved . Including a measurable impact (e.g., conversion drop %, time lost, error rates, business KPI affected) provides gravity and evidence . Example: “New trial users (who) often get stuck linking their bank account (problem), leading to 50% of sign-ups never activating (impact).” This one-liner should exclude any mention of solutions; it’s purely the pain point. It should also be easy to understand – avoid jargon. The idea is that anyone reading it immediately grasps the essence of the issue. By having this one-liner, you give your team a quick litmus test for scope: if a proposed feature doesn’t clearly help reduce that 50% drop-off (in the example), maybe it’s not in scope. One trick: after writing it, ask “so what?” – if the statement doesn’t answer why it’s important, refine it to include the consequence. The output is a pithy, memorable problem summary that can drive home the urgency and focus for the project. • /pm-problem:scope-constraints [problem] — outputs boundaries + explicit non-goals Key Points: For any defined problem, it’s important to set scope boundaries – clarifying what you will and will not solve. This ensures everyone knows the limits of the project. Start by re-stating the problem, then list non-goals: aspects that might be related but are out of scope . For example, if the problem is “users can’t easily share files externally,” you might state that solutions will cover sharing via link but not cover advanced permission management (non-goal), or that it’s for small files only (constraint, not handling >1GB files). Explicitly writing non-goals is powerful; it’s like saying “we accept that we are not solving X.” This prevents later feature creep (“Could we also add…?” – refer back to non-goals). Also note any constraints like technical or regulatory boundaries (e.g., “must work offline” or “cannot use third-party cloud due to compliance”). These act as design constraints from the start. A useful format is a bullet list under a “Out of scope” or “Non-goals” section in the PRD. For instance: Non-goals: 1) We are not building a full social network – no profiles or friending. 2) Not addressing enterprise admin controls in this phase. These statements often come from strategy (what you choose to focus on vs. not) . In sum, this output ensures clarity on problem boundaries: the team knows the playing field and can avoid veering off into tangents that dilute the effort. • North Star + KPIs — measurable outcomes Key Points: Define the North Star metric and supporting KPIs to measure product success. The North Star Metric (NSM) is a single metric that best captures the core value your product delivers and correlates with long-term business success . For example, for a ride-sharing product it might be “rides completed per week,” or for a SaaS app “active subscriptions.” Choose a metric that reflects customer value and growth – it’s your product’s ultimate outcome to drive. Once set, use it as a guiding light: all teams ask “Will this move the North Star?” . Next, break down the NSM into KPI tree of input metrics and guardrails. Identify the key input metrics (drivers) that influence the North Star. For instance, if NSM is “weekly active users,” inputs could be new sign-ups, activation rate, and retention rate. Visualize how these metrics roll up into the North Star (this hierarchy is sometimes called a KPI tree or metric tree). Also define guardrail metrics – secondary metrics to monitor so that in pushing the North Star, you don’t tank something else important . Guardrails are often things like performance, quality, or user satisfaction indicators (e.g., page load time, error rates, support tickets) that ensure you’re growing sustainably and not creating new problems. Finally, outline a measurement plan for tracking these metrics. Specify where and how each KPI will be measured – e.g., “Retention = % of users active 30 days after signup, tracked via analytics cohort report” . If new features are involved, ensure you have events/instrumentation in place to collect the needed data . By connecting North Star, input KPIs, and measurement details, you create a metrics framework where success is clearly defined and trackable. • /pm-metrics:north-star [product] — outputs North Star definition + rationale Key Points: This task yields a clear definition of your North Star Metric and why it was chosen. Describe the metric in precise terms (e.g., “Average Daily Active Users who complete at least one core action”) and explain how it captures the core user value. For example: “Our North Star is Minutes of content watched per user per day, because it reflects how engaged users are and is tied to our subscription revenue. Increasing this means users are finding more value (content) and we retain them longer.” The rationale should cover: how the metric aligns with user success and business success, and why it’s a leading indicator (i.e., moves earlier than ultimate revenue/profit). Often, you’ll note that when this metric goes “up and to the right”, other good things follow . Also mention characteristics that make it a good North Star: is it actionable by the team? (e.g., we can run experiments to influence it), is it not a vanity metric? Ideally provide a bit of context: “We considered metrics X and Y, but chose this because…”. For example, “We chose ‘weekly active teams’ over ‘total signups’ as our North Star, since active teams indicate real collaboration happening (true value), whereas signups can be high without engagement.” By explicitly stating the rationale, you ensure stakeholders buy in and understand this focus. The output is usually a short paragraph or slide: Metric name, definition (how exactly it’s calculated), and 2-3 bullet points on why it matters. This will guide all subsequent goal setting and prioritization. • /pm-metrics:kpi-tree [north-star] — outputs input metrics + guardrails Key Points: The KPI tree breaks the North Star into the specific metrics you will monitor and influence. Start with the North Star metric at the top, then identify 3-5 major levers or components of that metric. These are your input metrics (sometimes called drivers). For example, if the North Star is “monthly active users”, drivers might be “new user sign-ups per month”, “activation rate”, and “retention rate”. Draw or list them in a hierarchy under the North Star. For each input metric, you can further break it down if needed (e.g., “sign-ups” might break into traffic × conversion rate). This shows a cause-and-effect chain – improving those inputs should move the North Star. Next, add guardrail metrics to your tree (often attached at the level of North Star or major inputs). These are metrics you don’t want to tank while optimizing the NSM . For instance, if driving up “items sold” (NSM), you’d guard against “return rate” or “customer satisfaction” dropping. In the tree diagram, guardrails might appear as side notes or in a separate section. Make sure each guardrail has a threshold (e.g., “maintain NPS above 30” or “error rate < 0.5%”) to define acceptable bounds . The final result is a visual or structured list: North Star -> inputs -> (possibly sub-metrics), plus guardrails. It effectively communicates “Here’s how we’ll get there (inputs) and what we’ll watch to stay healthy (guardrails).” This helps the team prioritize projects affecting those inputs and keeps a balanced scorecard so that, say, growth doesn’t come at the expense of quality. • /pm-metrics:measurement-plan [feature] — outputs how/where metrics will be tracked Key Points: A measurement plan details what you will measure and how for a given feature or initiative. It ensures from day one that you’ll have the data to evaluate success. To create it, list the key metrics or events associated with the feature. For example, for a new “invite friend” feature, you might track “# of invites sent”, “conversion rate of invite (friend joins)”, and impact on retention. For each metric/event, specify the data source and implementation: e.g., Event: "Invite Sent" – tracked via frontend analytics (Mixpanel) when user clicks Send; Property: method (email/SMS); Success metric: conversion = invites that result in sign-up, measured by linking invite code usage in database. Essentially, it’s a tracking plan for the feature . Include any funnels or derived metrics too (like funnel from invite sent -> friend signed up -> inviter active 7 days later). Be clear on where each data point comes from (logs, analytics tool, database) and how often you’ll monitor it (real-time dashboard? daily report?). If using an analytics platform, you might define the exact event names and properties to be logged . Also consider qualitative measurement: e.g., “will run a user survey after feature use” if relevant. The plan should tie back to success criteria: ensure every success metric has a corresponding tracking mechanism. By laying this out, the engineering team knows what instrumentation to build, and the product team knows how they’ll gather evidence on the feature’s performance. Deliverable could be a table in the PRD or a separate doc, listing each metric, definition, and tracking method. This avoids the common pitfall of launching and then realizing you lack data to judge success. • Product strategy — positioning, constraints, “not doing” Key Points: A product strategy outlines how you will win in the market and ties the product vision to execution. It should concisely state who the product serves, what problems it will solve for them, and how the product will excel or differentiate versus competitors . It’s as much about choosing what not to do as what to do . For example, your strategy might target “busy professionals (who) need quick meal solutions (problem),” and your approach to win could be “provide a 15-minute meal kit service (solution) that’s healthier and faster than takeout (differentiator).” It would also explicitly state constraints like, say, “we will focus on dinner only, not lunch” or “not targeting budget segment initially” (i.e., not doing X). A good strategy provides a decision framework: when new ideas arise, team members can ask “does this align with our strategy (target users, core value prop)?” . Also include business context: e.g., key business goal (like revenue from subscriptions) and how the product strategy supports it, as well as any market conditions (regulations, tech constraints) that shape what you can or can’t do. The strategy might be captured in a brief document or one-pager for the team, including vision recap, target segment, value proposition, key differentiators, and strategic pillars or focus areas. Make sure it’s time-bound (often 1-2 year horizon) and revisited periodically. Ultimately, the strategy helps align the team and stakeholders on why and where you’re focusing, and it empowers saying “no” to out-of-scope ideas because you’ve documented the rationale behind your focus . • /pm-strategy:strategy-brief [product] [horizon] — outputs strategy doc (why now, where win) Key Points: This deliverable is a short strategy document for your product, tailored to a certain time horizon (e.g., 1-year strategy). In it, clearly articulate “Why now?” – the current opportunity or problem in the market that makes this strategy relevant. This could include market trends, competitive gaps, or user behavior changes that your product can capitalize on now. Then describe “Where to win” – which market or segment you will focus on and how you’ll win there. That includes your unique value proposition to that segment and any competitive advantage. For example: “Over the next 12 months (horizon), Product X will focus on mid-size e-commerce businesses (where) by offering an analytics tool that requires no developer setup (how we win). Market research shows increasing demand for no-code solutions (why now), and currently available analytics tools are too complex for this segment (gap).” Outline 2-3 key strategic pillars or themes that support this (e.g., “Ease of integration” and “AI-driven insights” might be pillars). Additionally, mention any constraints: e.g., “We are limiting to English-speaking markets initially” or “dependent on integrating with Platform Y by Q2.” This shows awareness of the playing field boundaries. The brief should also address how the strategy ties to business goals (e.g., how success will be measured – perhaps a target North Star metric or revenue goal). Essentially, this is a narrative that tells the product’s game plan: who and what we’re betting on and why it’ll work now. It provides context for the roadmap and day-to-day priorities, ensuring everyone knows the big-picture direction. • /pm-strategy:tradeoffs [options] — outputs decision matrix + recommendation Key Points: Often you’ll face multiple possible approaches – this task produces a trade-off analysis to aid decision-making. First, list the options you’re considering (could be product directions, feature A vs B, different technical solutions, etc.). Define the criteria important for the decision – for product strategy, common criteria might be user impact, revenue potential, implementation effort, risks, alignment with vision, etc. Create a decision matrix: options as rows, criteria as columns. Score each option on each criterion (e.g., 1-5 or High/Med/Low) . You might weight criteria if some are more important. Fill in qualitative notes too – e.g., Option 1 has high impact but also high effort and risk of regulatory issues; Option 2 is low effort but smaller market, etc. This structured comparison makes trade-offs explicit: you can see, for example, one option scores well on quick wins while another is a long-term play. Include any unknowns as part of risk (if one option is unproven, mark that). After analyzing the matrix, provide a recommendation – which option you recommend and why. It could be one of the options or a hybrid. The recommendation should clearly state the rationale, referencing the matrix (“Option B is recommended because it offers a good balance of impact vs. effort, and although Option A had higher potential revenue, its timeline and risk are not acceptable right now.”). This approach ensures transparency – stakeholders can see the logic behind the choice rather than it being subjective. The final output might be a slide or document with the matrix table and a narrative paragraph of the decision. It helps drive consensus by grounding the debate in objective criteria. • Prioritization — impact/effort/risk/learning Key Points: Product managers often have a long list of ideas; prioritization is about deciding what to do first. Use a framework that considers multiple factors such as impact, effort, risk, and learning potential. Impact estimates how much value an idea could deliver (to users or to business metrics). Effort gauges the resources/time required. Risk accounts for uncertainty or potential downsides. Learning addresses how much knowledge you’d gain even if an idea fails (important for innovation). Often, a simple Impact vs. Effort matrix or a scoring model like RICE (Reach, Impact, Confidence, Effort) is helpful . For example, RICE scoring will yield a numerical score by estimating each factor; higher scores indicate higher priority . You might also consider risk by favoring some low-risk quick wins and a few high-risk high-reward items – a balanced portfolio. Don’t prioritize solely on one dimension (e.g., just effort or just impact) – a low-effort item with trivial impact might not be worth it, and a high-impact idea with extremely high risk might need a spike or prototype first. Include qualitative considerations too: strategic alignment (does it support our North Star metric?), customer commitments, etc. The outcome of this step is a ranked backlog or clear ordering of what to tackle in what sequence, with rationale attached (“Feature X is top because it has huge impact and quick to do; Feature Y is next as a high-impact but higher-effort; Feature Z later due to uncertain ROI”). This allows you to communicate to stakeholders why you chose one thing over another and ensures resources are spent on the most valuable work first. • /pm-priority:score [ideas] [framework] — outputs ranked backlog + scoring rationale Key Points: Here you’ll apply a specific prioritization framework (e.g., RICE, ICE, MoSCoW, etc.) to a list of ideas and produce a scored & sorted list. Let’s say we use RICE: for each idea, estimate Reach (how many users it affects), Impact (how strongly it affects each user or key metric, typically on a scale), Confidence (how sure you are about reach/impact estimates), and Effort (typically in person-weeks or a t-shirt size) . Then compute the score (e.g., RICE = (Reach×Impact×Confidence) / Effort) . Do this for all ideas – it often helps to tabulate it. The output should list ideas ranked from highest score to lowest. Alongside each idea, include the values or a brief rationale: e.g., “Feature A: Score 720 – high reach (80% of users) * high impact (4/5) * confidence 90%, moderate effort (2 wks).” Also note if any scoring was subjective – the framework brings consistency, but it’s good to mention if, say, confidence is low. The backlog of ideas is now prioritized according to the framework, but remember to use judgement too – the top item by score should generally be pursued first, unless there are strategic timing issues or dependencies. The stakeholders can see the rationale in the numbers, which makes prioritization discussions more objective and less about personal opinion. This scoring exercise, when documented, also serves as a record so later on you can revisit why something was or wasn’t prioritized at the time. • /pm-priority:bet-sizing [top-ideas] — outputs effort bands + risk notes Key Points: “Bet sizing” means categorizing initiatives by the size of investment (small, medium, big bets) and considering the risk associated with each size. Take your top ideas or projects and assign an effort or cost band: for example, Small bet (days of work, minimal resources), Medium bet (a few weeks, moderate resources), Large bet (months of work, significant resources). This is often qualitative but based on initial engineering input. By labeling this, you can ensure you’re not doing only large bets at once – a mix is healthy (small bets give quick wins or quick fails to learn, big bets can drive big outcomes but take longer). For each idea, also assess risk: a large bet might carry high risk (many uncertainties, or if it fails it’s costly), whereas a small bet typically has lower risk (less lost if it doesn’t pan out). Note down specific risk factors: e.g., “This idea depends on user behavior change – risk: users may not adopt” or “technical risk: unproven AI model needed.” The output could be a simple table: Idea – Bet Size – Key Risks/Unknowns. It might also note reward potential, implicitly connecting with bet size (big bets should have big potential payoff to be justified). This helps in roadmap planning: you might decide to pursue a couple of small bets immediately (low risk, quick results), while scheduling a big bet but perhaps gated by a proof-of-concept first due to its risk. Communicating bet sizes and risks ensures stakeholders understand the level of investment and uncertainty. For example, “Project Gamma is a large bet (estimated 3-month build) with some market risk; we’re balancing it with two small, low-risk bets in Q1.” This creates transparency around the portfolio of work in terms of risk/reward. • MVP scope — smallest shippable learning unit Key Points: When planning an MVP (Minimum Viable Product), think in terms of the smallest functional product slice that can test your assumptions and deliver value. The MVP should aim to validate a hypothesis with minimal effort – it’s not just a smaller product, it’s a focused experiment. Identify the core features absolutely needed to solve the primary problem (your earlier problem statement) and exclude any nice-to-haves. A useful approach is to list all potential features, then ask for each: “Can we launch without this and still solve the core problem enough to learn?” If yes, it’s not MVP. Map features or requirements to the assumptions they test. For example, if one assumption is users are willing to upload a photo for a profile, your MVP might include profile photo upload. But if another feature doesn’t test a critical assumption or provide core value, push it to later. Essentially, differentiate MVP vs. later-phase features . Often a simple table works: Included in MVP: A, B, C (with reasons), Post-MVP: X, Y, Z (and why they can wait – e.g., “not needed for initial learning” or “nice-to-have polish”). Embrace constraints: it forces creativity (maybe you do something manually or with a simpler implementation in MVP). Also define what learning you expect from the MVP – e.g., “After MVP launch, we will know if users actually complete the task and find value in it (measured by retention or NPS).” By explicitly scoping MVP as the “smallest shippable unit that achieves learning X,” you guard against feature creep. Remember the MVP should still be viable – it must deliver some real value to real users, so don’t cut so much that it fails to solve any problem. The output is a clear MVP feature list and a list of deferred features, often with an assumption map showing which assumption each MVP feature validates. This aligns team and stakeholders on expectations: MVP is not the final product, but a stepping stone to test and iterate. • /pm-mvp:scope-slice [idea] — outputs MVP vs later list + assumption mapping Key Points: This will produce a delineation of what’s in the MVP “slice” of a product idea versus what is saved for later iterations, linked to assumptions. Start by reiterating the goal of the MVP – which user problem and which assumption you most need to test. For the idea, list features or components in two buckets: MVP Include and Later / Not in MVP. Under Include, list only those features that are critical to deliver the core user experience and to test the main assumptions. Next to each, note the assumption it addresses. For example: “Feature: one-click checkout – Assumption: convenience improves conversion.” Under Later, list features that are nice-to-have, can be added after validation, or address secondary problems. For each, you might note why it’s safe to defer (e.g., “manual reporting can suffice at low scale, build automation later”). The assumption mapping is key: it shows stakeholders that the MVP isn’t arbitrary – it is specifically designed to learn. If there are assumptions you choose not to test in MVP, state those and why (perhaps they’re lower priority or require scale). This mapping might be presented as a table or just inline notes. The output clearly communicates: “Our MVP will have A, B, C because we need to verify [critical hypotheses]. Features X, Y, Z will come later, as they refine the experience but aren’t needed to prove value.” This prevents scope creep by backing decisions with logic. It also sets up your iteration path – if MVP validates the key hypothesis, you know what the next features to add are (the ones in the Later list). Essentially, you’re slicing the idea to a minimal testable product, and everyone can see how that slice was chosen. • /pm-mvp:experiment-plan [mvp] — outputs what to learn + success thresholds Key Points: An MVP is an experiment; this plan outlines the experiment design. First, state the hypothesis or question: e.g., “We believe that enabling users to do X will result in Y improvement.” Next, specify what you want to learn from the MVP. This could be user behavior (will they use feature X? how often?), value perception (do they find it useful?), and impact on metrics (does retention increase?). For each learning objective, define a metric or observation to track. Then set success criteria or thresholds for those metrics – basically, what results would confirm the hypothesis versus what results indicate a pivot or change is needed. For example: Success criterion: “At least 20% of trial users engage with the new feature in the first week, and a 10% increase in trial conversion is observed.” These thresholds should be realistic yet tied to your hypothesis (maybe based on historical data or competitor benchmarks if available). Also define the duration or sample size of the MVP test – e.g., “We will run the MVP for 4 weeks or until 500 users have tried it, whichever comes first.” Include any qualitative validation: e.g., conduct 10 user interviews during MVP to gather feedback; success might be “majority can articulate the value without prompt.” Essentially, this is like an A/B test plan (if applicable) or a pilot rollout plan. By having explicit success/failure criteria, you avoid the trap of cherry-picking data later. If criteria are met or exceeded, likely move forward (maybe scale up or invest more). If they are not, you pivot or iterate. Document also any guardrail metrics during experiment (ensure no severe drop in other KPIs). The final plan should read: “We will launch MVP to [segment]. We expect to learn [these things]. We will measure [metrics] and consider it a success if [thresholds]. If success, next step = scale; if not, we’ll analyze feedback and consider pivoting [aspect].” This gives everyone a common understanding of how the MVP’s outcome will be judged. • PRD/spec — goals, scope, flows, acceptance criteria Key Points: A Product Requirements Document (PRD) or spec is a comprehensive description of a feature or product for the engineering/design team. It usually starts with background and goals: why we’re doing this (link to the problem statement and success metrics). Then scope: what’s included (and sometimes explicitly what’s out, i.e., non-goals). It will describe user flows or use cases in detail – typically with step-by-step narratives or flow diagrams of how a user will interact with the product to achieve something. Importantly, a PRD defines requirements in a way that’s solution-agnostic enough to allow creative implementation, but clear enough to avoid ambiguity. Each feature or user story should have acceptance criteria: specific conditions that must be met for the implementation to be considered complete and correct . For example, “Given the user has entered valid data, when they click submit, then X happens. If invalid, Y error is shown.” These criteria ensure testability and alignment on expected behavior . The PRD might also cover edge cases (error conditions, empty states) and any constraints (performance needs, compatibility, etc.). Keep language clear and avoid implying the technical solution unless necessary (focus on what, not how). Additionally, include any UX sketches or wireframes (or link to design docs) to illustrate flows, and tracking requirements (what analytics/metrics to collect). A good PRD also has a section for open questions or things that need validation – which invites team input. The PRD should be reviewed with the team to fill those gaps. By the end, the PRD/spec serves as the single source of truth that developers, QA, design, etc. can reference during implementation. It reduces miscommunication because all details (business context through to acceptance criteria) are captured in one place. • /pm-prd:write [business] [app] [description] — outputs PRD draft + missing-info questions Key Points: This prompt implies using an AI (Claude) to draft a PRD given some inputs, but in general, when writing a PRD you’ll produce a draft of all sections and also flag questions where info is missing. Start with the header info: feature name, author, date, etc. Then a Summary: one paragraph on what this feature is and why we’re building it (business goals, user problem). Next, Objectives/Goals: bullet points of specific outcomes (e.g., “Improve conversion by X%” or “Allow users to do Y which they couldn’t before”). Scope: what’s included (features, use cases) and Out of Scope if needed for clarity. User Stories / Use Cases: list each major interaction scenario, e.g., “As a [user], I can [do something] so that [benefit].” For each, provide details. User Flow: maybe embed a simple flow diagram or enumerate steps for key flows. UI/UX: reference wireframes or designs if available, or describe the interface changes. Functional Requirements: itemized, e.g., “The system shall do X.” Each should later map to something testable. Under each, write Acceptance Criteria clearly . Also note Non-functional Requirements (performance, security, etc.) if important. Finally, include Open Questions / Assumptions: list things that need decision or confirmation. For instance, “Q: What happens if payment fails? (Design needed)” or “Assumption: We will reuse the existing login component.” Highlighting these missing pieces is important so they aren’t forgotten – and stakeholders can help resolve them. The output of this command would be a structured draft PRD containing all the above, with [TODO] or question markers where info is incomplete. It provides a starting point that the human team can then review and fill in. Essentially, you want a comprehensive draft that’s maybe 80% complete and clearly calls out the remaining 20% to clarify. • /pm-prd:acceptance-criteria [prd] — outputs testable AC + edge cases Key Points: Given a PRD, this focuses on extracting or writing the Acceptance Criteria (AC) for requirements. Acceptance criteria are the conditions that a product must satisfy to be accepted by the user or QA . They should be written in a clear, testable format – often as bullet points under each user story or requirement. For example: “When [action], then [expected result]”. This command would output a list of AC for each major functionality described in the PRD. E.g., if PRD says “User can reset password via email,” AC might include: “If user enters a valid registered email, a reset link is sent to that email.”, “If email is not registered, an error message ‘Email not found’ is shown.”, “Reset link expires after 24 hours.” etc. These cover normal and edge cases. Indeed, good AC think of edge cases: error conditions, boundary values, etc., effectively enumerating how the system should behave in all those scenarios. We might use the Given/When/Then format from BDD (Behavior-Driven Development) to be precise. For instance: Given a user who has an account, when they request password reset, then an email is sent and a confirmation message displayed. Including edge cases like “Given a user enters an invalid email format… then show validation error.” The result is that QA can take these criteria and write test cases, and devs know when they are “done” implementing a function (when all criteria pass). It reduces ambiguity (“Did we consider what happens if X?” — yes, if it’s in AC). Thus, this output ensures every scenario drawn from the PRD is accounted for with an expected outcome, leaving little room for subjective interpretation. • /pm-prd:release-notes-draft [prd] — outputs user-facing release notes draft Key Points: After building the feature, you’ll need to communicate changes to users. This outputs a draft of Release Notes based on the PRD. Release notes should be user-friendly summaries of what’s new or improved, focusing on the value or changes users need to know. They often include a high-level bullet list of new features, enhancements, and bug fixes. For example: “New: You can now upload profile pictures in the app – personalize your account (Feature X). Improved: Faster checkout process – we streamlined from 5 steps to 3 (Feature Y). Fixed: Issue causing notifications not to appear for some users.” The draft should translate technical changes into benefits or clear descriptions. If the PRD had multiple user stories, each likely becomes a bullet point. Use positive language and, if appropriate, celebratory tone for new capabilities (“We’re excited to introduce…”). However, keep it concise. Also, consider if any action is required from users (e.g., “You may need to log in again” or “This update will require iOS 14+”). Ensure that any significant UI changes or removed features are noted to avoid user confusion. Essentially, this is packaging the PRD’s outcomes into an announcement format. It might be structured as: Introduction line (one sentence about the update), then list of changes grouped by New / Improved / Fixed or similar. Optionally, include a “how to access” if it’s a hidden feature. The output being a draft means it may then be reviewed by marketing or support for tone, but it should be close to ready for publishing to users or internal teams. • Roadmap planning — sequence bets + milestones Key Points: Roadmap planning is about sequencing initiatives over time to achieve the strategy. After prioritization, you slot features or projects into time frames (often quarters or months). Ensure a sensible mix (as discussed, maybe some quick wins, some big bets) and take into account dependencies and milestones. A Now-Next-Later roadmap is a popular lean format: items the team is working on Now, items coming up Next, and items Later (future/backlog) . This gives a rough sequence without committing to specific dates, which is helpful when uncertainty is high. For more date-driven roadmaps, you might plot by quarter. Be sure to identify key milestones – e.g., an MVP release, a beta launch, a “Launch v1” – as anchor points. These milestones should have specific outcomes (like “internal beta complete” or “100 users onboarded”). When planning, consider resources and capacity – you can’t do everything at once. Mark any dependencies between items (for example, “API refactor must happen before mobile app update”); often, visual roadmap tools will show dependency lines or you note it in text. The goal is a roadmap that tells a story: “First we will do X (because we need to learn/prove Y), then that enables us to tackle Z,” etc. Also align milestones to external dates if needed (like a conference or end of financial year, etc., if relevant). The roadmap should reflect the strategy – near-term items that execute on current strategy, later items might be more exploratory or contingent on earlier results. It’s important to communicate that roadmap is subject to change (especially anything beyond ‘Now’ or the current quarter, which is more of a plan than a promise). The planning process should also involve stakeholders to ensure expectations are managed. The output typically is a roadmap diagram or table, and a written narrative explaining the sequencing and any key milestones/dependencies. • /pm-roadmap:now-next-later [initiatives] — outputs Now/Next/Later board Key Points: This command likely transforms a list of initiatives into a simple Now / Next / Later roadmap. In practice, gather your initiatives and assign each to one of three buckets: Now (currently in progress or up next within the immediate term, e.g., this quarter), Next (planned soon after, e.g., next quarter – the next priorities after current work), Later (on the roadmap but not detailed or scheduled yet, maybe 6+ months out). The output would be a board or list grouped by these categories. For each initiative, include a short description. For example: Now: 1) Launch MVP of feature X, 2) Improve onboarding flow. Next: 1) Begin development of feature Y, 2) Research integrations. Later: 1) Expand to new platform Z. This format is high-level and focuses on prioritization rather than dates . It’s easily digestible and communicates direction without over-precision. It also emphasizes that priorities can shift (items can move between Next and Later as you learn). Often, Now is a small set (what the team is doing right now), Next is also relatively short list, and Later holds the backlog of big ideas or future bets. The “board” can be visual (three columns). The generated output should be something a PM could share with stakeholders to show, “Here’s what we’re doing, what’s coming soon, and what’s on our radar for later.” Keep each item’s wording non-technical and value-oriented if possible (“Improve referral program (increase viral signups)” instead of “Tweak code in module…”). This ensures all readers understand it. • /pm-roadmap:milestones [initiative] — outputs milestones + dependencies Key Points: For a given big initiative, this produces a breakdown of major milestones and any dependencies among them. Start by identifying the key phases or deliverables in the initiative’s life cycle. For example, if the initiative is “Launch new mobile app,” milestones might be: Design Complete, Beta Release, Public Launch, v1.1 Update. Under each milestone, add a target date or timeframe if known, and describe what it entails (e.g., “Design Complete – all screens and user flows approved by stakeholders (target June 1)”). Then list dependencies: these could be internal (one milestone depends on another team’s deliverable) or external (e.g., “App Store approval” is a dependency for launch). It’s helpful to phrase them like “Milestone B (Dependency: Milestone A must be finished first)” or “Feature X is dependent on API Y from backend team”. You might show a sequence: Milestone 1 -> Milestone 2 -> Milestone 3, noting the arrows as dependencies. Also consider parallel vs sequential – some tasks can run in parallel (note if so), others are strictly sequential. If the initiative is part of a larger program, mention cross-team dependencies too (“Marketing campaign start depends on Launch date”). The output likely is a list such as: Milestone 1: … (depends on …), Milestone 2: … (depends on …), etc. This gives the team a map of how the work can be staged and highlights anything that could block progress. With this, a PM can facilitate coordination (ensuring dependencies are addressed ahead of time) and track progress milestone by milestone. It also helps in risk management – if a dependency is at risk, the milestone slips. So clearly documenting them is key to proactive management. • Post-launch analysis — learn, decide next actions Key Points: After launching a product or feature, it’s critical to analyze its performance and gather learnings. Post-launch analysis involves looking at the metrics (quantitative data) and qualitative feedback to assess what happened. Key questions: Did we meet our success criteria? What moved (improved) and what didn’t? For metrics: compare against the baseline or goals. For example, “Feature X was supposed to increase conversion by 5%, but we only see 2% – why?” Break down metrics by segment if needed to find patterns (maybe new users loved it but power users didn’t, etc.). For qualitative: read user feedback, support tickets, social media, run surveys – what are users saying? Often this reveals why the metrics look like they do (“Users are confused about the new button, thus usage is low”). Compile these findings in an impact review document. Highlight successes: e.g., “Page load time improved by 1s, user satisfaction up, matching our hypothesis on speed.” And failures/neutral results: “No significant change in retention observed in first 2 weeks.” Try to explain why for each . It may involve going back to research mode or examining funnels (e.g., maybe people try the feature but drop off at step 2). Once analysis is done, convene the team to decide next actions. These could be fix (address a bug or UX flaw causing issues), iterate (tweak or add something to better solve the problem based on feedback), or pivot/kill the feature (if it proved not valuable or harmful). Prioritize these next steps by impact and effort. Essentially, the post-launch phase completes the feedback loop: you launched an experiment (MVP), now use real data to inform what to do next. Document the learnings – even if a feature is shelved, the insight is valuable (e.g., “users don’t want X, they really wanted Y instead”). This approach ensures continuous improvement and that you’re not just moving on blindly after launch, but rather being data-driven and user-driven in subsequent decisions. • /pm-postlaunch:impact-review [metrics] [qual] — outputs what moved, what didn’t, why Key Points: This is essentially a report of the launch’s impact. Using the provided metrics (quantitative results) and qualitative inputs, summarize the outcomes. For each key metric you were tracking (e.g., adoption rate, conversion rate, error rate), state how it changed post-launch. Use comparisons: “Signup conversion increased from 20% to 26% (a 6 pp uplift) within 2 weeks of launch.” or “No significant change in daily active users (retained ~35% one week after sign-up, same as before).” Highlight where things moved as expected (or better) and where they did not . Then incorporate qualitative findings to explain or add color. For instance: “Support tickets about the new feature: 50% were ‘how do I use it?’ – indicates some usability issues.” or “Beta user interviews indicated confusion at step 3, which aligns with drop-off there in the funnel.” Essentially, pair what happened with possible reasons why. If something didn’t move that you hoped would, propose hypotheses: “We expected X to increase, but it didn’t – possibly because Y (as seen in user comments).” If something unexpected happened (maybe a metric went down), note that too and why it might be (maybe an unintended side effect). Organize by goal/metric for clarity: e.g., Goal 1: Improve engagement – Result: +10% session length (good, likely due to new content feature). Goal 2: Increase sign-ups – Result: no change, possibly because marketing didn’t drive more traffic. Conclude each with an insight (the “why”) so it’s not just raw data but interpreted information. The final output is a clear narrative of the launch’s impact: successes, shortfalls, and reasons. This prepares the team to make informed decisions (and is often shared with executives or other teams to update them on progress). • /pm-postlaunch:next-actions [findings] — outputs prioritized fix/iterate/kill list Key Points: Based on the findings from the impact review, this step lists the next actions the team should take, prioritized. Likely categories: Fix issues (if there were bugs, UX flaws, or performance problems uncovered – these go to the top of the list especially if they impact existing users badly), Iterate on the feature (improvements or changes to better achieve the goals, derived from feedback and data), or in some cases Kill/roll back the feature (if it fundamentally didn’t work or caused more harm than good). For each action, provide a brief justification tying it to the findings. For example: “Fix: Address slow load time on mobile (users reported slowness, and metric X shows 3s load – likely hurting adoption). Iterate: Redesign onboarding tooltip – 40% of users missed the key step, we can improve guidance. Kill: Remove feature Y for now – it saw low usage (5% adoption) and confused some users (many questions in support), focusing on core flows instead.” Also consider prioritization: rank these by importance/urgency. Fixes that mend bugs or major pain should be P1. Iterations that could significantly move a KPI might come next. Nice-to-have improvements gleaned from minor feedback might be later or even deferred. If the decision is to pivot or drop the initiative, note what will be done (e.g., “sunset feature by end of quarter, inform users, and re-allocate team to other projects”). By listing these actions, you effectively close the loop on the product development cycle for this feature: you used the evidence to decide what to do after launch. This also is a reality check: sometimes the best next action is to do nothing further (if all is well or if strategy shifts). But typically, you’ll have at least some improvements. Present the list in a format like: Action – Type (fix/iterate/etc.) – Priority – Rationale. This helps planning the next sprint(s) and demonstrates to stakeholders that you’re responding to results, continuously improving the product.

⸻

UX / Product Design (UX/UI/Content) • User journeys — end-to-end flows Key Points: A user journey map is an end-to-end visualization of a user’s experience accomplishing a specific task. To create one, define the stages the user goes through (e.g., Awareness -> Consideration -> Onboarding -> Usage -> Support). Then for your product’s specific task, outline each step the user takes, from start to finish (including any steps outside the product, if relevant). At each step, note the user’s goal or action, the touchpoints (what interfaces or channels they use), and importantly the pain points or emotions the user might have . For example, journey for “order food” might start at “User feels hungry (trigger) -> opens app -> browses menu -> adds item to cart -> checkout -> waits for delivery -> receives food -> feedback.” At “waits for delivery” stage, a pain point might be anxiety about order status if there’s no update (emotion: anxious). Highlighting these pain points is key , as it shows opportunities to improve. Also identify delight moments or what’s working well. The journey map helps designers see the big picture beyond individual screens – understanding context (e.g., if user is in a hurry at step X, design must be quick). It ensures you consider all steps (even error paths or what happens if user drops off). By mapping the journey, you can communicate to stakeholders the user’s perspective and ensure the solution addresses every stage coherently. The output might be a diagram or series of storyboard-like panels showing each step with annotations about user thoughts and pain points. • /ux-journey:map [persona] [task] — outputs step-by-step journey + pain points Key Points: This command would produce a detailed journey map for a given persona performing a task. Expect a sequence of steps (usually numbered or in swimlanes for stages). For each step, include the action or what the user does, the context or touchpoint (e.g., “on mobile app”, “receives email”), and any pain point or obstacle encountered . For example: 1. Alice decides she needs a ride (pain: unfamiliar with local transit options). 2. She opens the RideShare app (pain: login required after update, causing delay). 3. She enters destination (pain: address auto-complete is confusing)… 4. She reviews driver options (positive: sees driver rating)… 5. Waits for pickup (pain: car took longer than ETA, felt uncertain). And so on until task completion. The output calls out each pain point in context, which helps UX designers target those for improvement (e.g., maybe add clearer progress indicator during waiting stage). This journey could also mention user thoughts or feelings at each step (“Alice feels frustrated here…”). It’s essentially capturing the user’s narrative of using the product. This is useful to ensure empathy and that design discussions focus on the user’s progression through a flow, not just isolated screens. • /ux-journey:edge-cases [flow] — outputs edge-case list + recovery paths Key Points: Every user flow has edge cases – unusual or error scenarios that might occur. This output lists those cases and how the UI/UX should handle them (recovery paths). To produce it, step through the happy path of the flow and ask “what if” at each step: What if the user does something unexpected? What if external systems fail? What if input is missing or wrong? For example, in a checkout flow edge cases include: credit card declined, inventory gone out of stock during checkout, user’s session times out, etc. The document would list each such scenario: e.g., “Edge Case: Payment fails (card declined) – Recovery: Show error message with decline reason and prompt user to try a different payment method.” Or “Edge Case: User loses connectivity on step 3 – Recovery: app detects offline, shows ‘retry’ option and saves progress.” Essentially, define how the design will gracefully handle errors or atypical inputs, ensuring the user isn’t left stuck or confused. A good UX anticipates these problems and provides clear feedback or a way to fix the issue (like undo, error inline messages, confirmation prompts for destructive actions). The output ensures designers and developers consider and implement for these less common scenarios. It reduces the chance of releasing a flow that works only in perfect conditions but frustrates users when something goes wrong. • Information architecture — navigation + structure Key Points: Information Architecture (IA) is about organizing and labeling content or features so that users can navigate intuitively. It often results in a sitemap (for an app or site) and a taxonomy of content. Designing IA starts with understanding what main sections or functions the product needs, and how they relate. For navigation, consider what should be top-level menus vs. submenus. Aim for a structure that matches users’ mental models – e.g., grouping related features under a category that makes sense to them. Use card sorting or other research to validate grouping if possible. The IA should also factor in scalability (can we add more items later logically?). Output typically includes a site map diagram showing the hierarchy of pages or screens. It might also include definitions of each section’s purpose. Meanwhile, a taxonomy covers how content is classified – e.g., for a knowledge base, defining categories and tags for articles, naming conventions, etc. Consistent naming is crucial for IA – pick labels that are clear and consistent (e.g., don’t use “My Profile” in one place and “Account Settings” in another if they refer to same concept). A good IA makes it easy for users to find what they need with minimal clicks and without getting lost. In summary: structure the product’s information and navigation in a logical, user-centered way before diving into detailed screens. • /ux-ia:sitemap [feature] — outputs sitemap + page responsibilities Key Points: Given a feature or entire product, this will produce a sitemap: a diagram or list of screens/pages and how they connect. It should list each screen and maybe a brief note on what it’s for (its “responsibility”). For example: Home -> Dashboard (shows summary & links to main sections), Dashboard -> Profile (user info & settings), Dashboard -> Reports -> Specific Report, etc. For a new feature within an existing product, it might show where it slots into navigation: e.g., Main Menu -> New Feature -> Subpage. For each page, clarify its purpose: e.g., “Report List – lists all user’s reports, allows creating new report,” “Report Detail – displays a specific report with data visualization.” Showing responsibilities ensures no two pages overlap in purpose (avoiding confusion) and everything needed is accounted for. Also, the sitemap can indicate navigation mechanisms (e.g., whether it’s a hierarchical menu or cross-linked). This output helps designers and devs get a shared understanding of the overall structure and how a user would move between pages. It also helps spot if anything is missing (like “we don’t have a page for editing X, do we need one?”). Essentially, it’s the blueprint of the site/app’s structure. • /ux-ia:taxonomy [content-types] — outputs naming + grouping rules Key Points: Taxonomy in UX refers to the classification of content. This output will define how different content types or items are named, grouped, and related. For example, suppose the product manages “Projects” which contain “Tasks” and “Files.” The taxonomy would clarify those terms and any hierarchies or tags. It might specify: Content Types: Project, Task, File; Hierarchy: Projects contain Tasks and Files; Attributes: each Project has a Name, Deadline, etc.; Naming conventions: e.g., use singular nouns for labels (“Project” not “Projects” in navigation label), avoid synonyms (decide between “Team” vs “Group” consistently). If there are categories or tags, define those sets and rules for applying them. The taxonomy could also cover how things are grouped in the UI – e.g., “We group tasks by status (To-Do, Doing, Done) – those statuses form a taxonomy for task state.” Or for an e-commerce: taxonomy of products (Category -> Subcategory). Basically, this deliverable ensures the product has a coherent content organization and consistent terminology. It prevents situations like the app calling something “Records” in one place and “Entries” in another (pick one term). It also guides any filtering or navigation logic. For instance, “All knowledge base articles are tagged with one of 5 topic tags and one of 3 user levels; these tags are used for filtering in UI.” The rules might include pluralization, capitalization (maybe all section names are Title Case), etc. It’s like a style guide for information. This is especially important in content-heavy applications or where new data types are introduced so everyone is aligned on how to reference and organize them. • Wireframes — validate flow fast Key Points: Wireframes are low-fidelity sketches of the UI, focusing on layout and flow without the distraction of visual design. The goal is to validate the structure and sequence of screens quickly. When creating wireframes, use simple boxes, placeholder text (“Lorem ipsum” or generic labels), and basic icons to represent content. Concentrate on the key elements on each screen (navigation bars, content sections, buttons) and how the user will move from one screen to the next (e.g., linking the wireframes with arrows or flow annotations). Wireframes should be annotated if not obvious – e.g., “This is where the product image will go”, “On clicking X, goes to Screen Y.” They allow you to check: does this flow make sense? Did we forget any necessary step or info? It’s much easier and cheaper to adjust a wireframe than high-fidelity designs or code. Engage stakeholders or even users (in quick guerrilla tests) with the wireframes to see if they understand the layout and flow. It’s also useful for the dev team to estimate complexity early on. Essentially, wireframes get everyone on the same page about what we’re building before worrying about how it looks. Keep them simple – grayscale, no fancy images – so the focus is on UX structure. They can be created on paper or using digital tools (Balsamiq style or just on a whiteboard). The output should cover each major screen in the journey and demonstrate the primary use cases. • /ux-wireframe:flow-screens [journey] — outputs screen list + key states Key Points: This would enumerate all the screens involved in a given user journey (from the journey map perhaps) and note the key states of each. For example: Login Screen (states: blank form, error state for wrong password), Dashboard (normal state with data, maybe an empty state if no data), Settings Screen, Item Detail Screen (state: loading, populated, error if item not found). By listing the screens, you ensure you wireframe each one. By listing states, you remind to design those variants. The deliverable might look like: • Screen 1: [Name] – content/sections and if any conditional states (empty vs filled, etc.). • Screen 2: [Name] – … It ensures completeness: teams often design the “happy state” but forget empty or error states – explicitly listing them prevents that. Also it gives a checklist for wireframing (“did we create the wireframe for error state? if not, do it.”). This helps developers too, who will need to implement those states. In summary, it’s a structured breakdown of the flow into discrete screens and sub-states, serving as a blueprint for wireframing and later design. • /ux-wireframe:review-checklist [wireframes] — outputs usability checklist Key Points: After creating wireframes, reviewing them with a usability checklist ensures they follow UX best practices. Such a checklist might include: Clarity (Is it obvious what each button or element does? Are labels clear?), Consistency (Are similar actions/buttons consistent across screens?), Feedback (Is it clear when an action is processing or completed? e.g., placeholders for error messages or loading indicators), Affordance (do interactive elements look clickable/tappable?), Hierarchy (Does the layout clearly show what’s primary vs secondary information via size/placement?), Accessibility basics (is text large enough in concept, have we accounted for color contrast in later UI?), Error handling (did we provide a way out or error messages for wrong inputs?), Edge cases (from earlier list – did we include designs for them?), Navigation (Is it easy to get where you want and back? breadcrumbs or back buttons present?), and CTAs (Is the primary call-to-action evident on each screen?). The output would be a list of these items and a note if the wireframe meets them or what to improve. For example: “- Clarity: The icon on top right unclear (consider adding label). - Feedback: No loading state shown for form submission (add that).” Essentially, it’s like a heuristic evaluation of the wireframes. By doing this check, you can catch and fix UX issues early, before visual design or development. It’s much easier to tweak a wireframe to add an error message placeholder than to redesign later. This ensures the wireframes aren’t just conceptually correct, but also align with good usability principles. • High-fidelity UI — final screens and states Key Points: High-fidelity UI design is where the wireframes are brought to life with actual visuals: real layout proportions, colors, typography, images, and so on, according to the product’s style. At this stage, you design every screen in detail, including all the different states (default, hover, active, error, loading, empty, etc.) for interactive elements. It’s important to maintain consistency with your design system or established patterns. Ensure accessibility (contrast, font sizes) in these final mocks. Also consider platform-specific guidelines (material design for Android, HIG for iOS, etc.) if applicable. The output is typically a set of polished mockups, often accompanied by a style guide or redlines for spacing. These will be what developers implement, so they should be thorough and cover corner cases visually. Also, prepare assets like icons or illustrations as needed. The high-fi design should be validated with stakeholders or users via prototype if possible (clickable prototype to test the look and feel and minor UX adjustments). Once finalized, we hand these off to dev with any notes. Essentially, this step answers “exactly what will the user see?” and should leave no ambiguity in visuals. • /ux-ui:spec-states [screen] — outputs states (loading/empty/error/success) Key Points: For a given UI screen, this outlines (and likely provides visuals for) all of its important states. Using, say, a data list screen as an example: • Loading state: what shows while data is fetching (e.g., a spinner or skeleton UI). • Empty state: if there’s no data (e.g., user hasn’t added anything yet) – maybe show an illustration or message “No items yet. Click Add to create one.” • Error state: if the data load fails (e.g., “Oops, something went wrong. [Retry]”). • Success state: in contexts like form submission, what confirmation the user gets (e.g., “Your profile has been updated!” with a success toast). Designing all these states ensures a polished UX. The spec should also indicate any transitions (does the error state slide in? does success message auto-dismiss?). By listing them, it acts as a checklist for dev to implement and for QA to test. It also helps avoid the scenario where an error occurs and no designed message is there (so user sees a blank or a raw error). So this output might be a mini-spec per screen, detailing how to handle various typical states an interface might need to handle. It’s often part of the design deliverables (multiple artboards for each state or an annotated single artboard). • /ux-ui:handoff-notes [design] — outputs dev handoff notes + components used Key Points: When handing off high-fidelity designs to developers, it’s helpful to include notes that clarify functionality and references to design system components. Handoff notes might cover: • Spacing and sizing guidelines (though devs can often inspect this in modern tools, notes can emphasize key padding or responsive behavior). • Any non-obvious behavior: “The header remains sticky on scroll,” or “This button is disabled until form validation passes.” • Animation details if any: “Modal fades in over 0.3s.” • Components: e.g., “Uses standard Card component from our design system for each item,” or “This is the Primary Button component with the icon variant.” • Assets: provide links to icon assets or specify if an icon is from a library. • If any fonts or colors in design are new or special, note their values (but ideally design uses the system tokens). • How it scales/responsive: e.g., “On mobile, this sidebar becomes a bottom tab bar.” • Accessibility: e.g., “Provide alt text for this image: …” Essentially, notes to bridge any gaps between static design and interactive implementation. Components reference ensures devs reuse existing UI components where possible instead of creating new styles. The output could be a document or simply comments in the design tool or a handoff platform. It helps devs grasp the intent quickly and reduces back-and-forth. For example, without notes dev might not realize a list item is clickable if the design doesn’t explicitly show a hover state—notes can clarify that. The goal is a smooth transition from design to code with minimal interpretation issues. • Design system alignment — components, patterns, documentation Key Points: Throughout design, ensure you’re leveraging a design system – a set of reusable components and styles. Alignment means that when designing new screens, use existing components (buttons, inputs, cards, etc.) where possible rather than inventing new ones. If something truly new is needed, consider adding it to the system. Also follow the established patterns for interactions; for example, if your system has a standard modal style, use that for all dialogs. Part of alignment is also updating the design system documentation if you introduce variations or new components during this project. This ensures consistency across the product and speeds up both design and dev (since devs might already have code for existing components). Also consider accessibility patterns from the system (like focus states, etc.). Essentially, no screen should look “out of place” from others. Use the same color palette, typography, spacing scale, etc., as defined. If deviations occur, have a good reason. Alignment also means checking that new designs don’t conflict with or duplicate something in the system. If they do, better to adjust to fit system or evolve the system deliberately. So the action item is often to do a component audit and spec (the next two bullets) to make sure of this alignment. • /ux-ds:component-audit [screens] — outputs reused vs new components list Key Points: This is a review of the designed screens to itemize all UI components present and categorize them as either existing (reused) from the design system or new. For example, in a screen, you might identify: header (existing global header), form fields (existing text input, dropdown components), a new fancy multi-select tag input (not in current system – new), a custom calendar date picker (maybe new), etc. The output could be a table: Component – Source. E.g., “Primary Button – exists (Button/Primary in DS)”; “Search Bar – exists (Search Input component)”; “Tag Selector – NEW (need to design spec for this)”; “Sidebar Menu – exists (using Navigation Drawer pattern)”. This helps both design and dev: dev will know what can be directly used from their component library and what must be built custom. For the new ones, it signals that design needs to create a detailed spec (next bullet) and possibly incorporate it into the design system for future reuse. Also, if too many new components are appearing, it might prompt reconsideration: are we diverging unnecessarily? Often, a minor variant can be done by extending an existing component rather than a whole new thing. The audit ensures nothing falls through the cracks – every piece of the UI is accounted for in terms of implementation. It’s also good for backlog: each new component likely is a distinct work item for dev (and maybe for design system team to document). • /ux-ds:component-spec [component] — outputs props, variants, do/don’t Key Points: For any new UI component (or an existing one that’s extended), produce a specification similar to how it would appear in a design system documentation. This includes: a description of the component’s purpose and usage, all its properties/attributes (props) that can change (e.g., for a button: label, size, state (default/hover/disabled), icon optional, etc.), and variants (different styles or configurations, like “primary vs secondary” button, or “large vs small” size). Provide visual examples of each variant. Also list states (normal, hover, active, focus, disabled, error if applicable). Additionally, guidelines: Dos and Don’ts for using the component. E.g., for a modal component spec: Do use for blocking important tasks, Don’t use for small tooltips or non-critical info; or a date picker spec: Do show it inline for full-page scheduling, Don’t use if only needing month/year selection (use simpler dropdown). The spec might also note accessibility considerations (like “this component must have ARIA roles set like so” if relevant, or “All images in carousel must have alt text”). By articulating props and variants, you essentially give devs a blueprint for building the component in a modular way (like props in React or parameters in any UI framework). It also guides designers in future how to use it consistently. This output ensures the component is well thought through beyond the immediate use case, considering possible variations. It effectively adds the component to your design system’s language. • Content + microcopy — labels, errors, empty states, onboarding text Key Points: Microcopy refers to the small bits of text in the interface that guide or inform the user: labels on buttons and fields, tooltip text, error messages, empty state instructions, onboarding prompts, etc. Good microcopy is crucial for UX – it should be clear, concise, and in the product’s tone of voice. This task ensures all these texts are crafted intentionally. That means: review every label and text on wireframes or design – are they understandable? Use action verbs on buttons (“Save Changes” vs “Submit”), use user-friendly language (avoid technical jargon in errors). Write helpful error messages that not only state the problem but if possible how to fix it (“Password too short – must be at least 8 characters”). Empty states should encourage the user what to do next (“You have no notifications – check back later” or better, “No items yet. Click ‘Add Item’ to get started.”). Onboarding/tutorial text: ensure it succinctly explains value or next steps (“Welcome! Let’s set up your profile so you can start using XYZ.”). Also maintain consistency – use the same terminology as defined in your taxonomy (don’t call it “projects” in one place and “assignments” in another). It often helps to have a content style guide (voice and tone guidelines) and follow that (e.g., maybe your product voice is friendly and casual, or formal and concise). Before finalizing, read the microcopy out loud or test with a user if possible to see if it’s understood as intended. Every piece of microcopy is part of the UX and can reduce confusion significantly if done well. So devote time to it, don’t treat it as filler text. The outcome might be a document or spreadsheet of all key microcopy strings for the feature (sometimes used for localization later too). • /ux-copy:microcopy-pack [feature] — outputs copy for all UI strings + tone rules Key Points: This would assemble a “microcopy package” for a feature – essentially a list of every user-facing text string in the UI of that feature, along with guidance on tone/voice. For example, list out: screen titles, button labels, field labels, tooltip texts, error messages, success messages, empty state messages, onboarding or instructional text, confirmation dialogs, etc. Next to each, provide the actual copy that should be used. If needed, include context or usage notes (e.g., “{username} will be replaced with the user’s name in this greeting message”). Also, describe the tone: if your product has a voice/tone guideline (like playful vs. professional), and how it applies here. For instance, maybe your tone is friendly; so an error message might say “Whoops, something went wrong! Please try again.” – that’s friendly. Or if it’s professional: “Error: Could not save data. Please try again.” The pack ensures consistency – not only within this feature but across the product. It’s also handy for localization – having all strings in one place. If multiple team members write different parts, consolidating avoids contradictory terms. Tone rules might include things like: “We use sentence case for all alerts. We say ‘please’ in errors to be polite. We avoid exclamation points except in success messages to avoid alarming the user,” etc. Essentially a mini style guide + the actual content for this feature. This output becomes the reference for devs implementing text in the UI and for reviewers to sign off the wording. • /ux-copy:error-messages [errors] — outputs user-friendly errors + next steps Key Points: For a given set of possible error scenarios, this will craft the actual error messages shown to users, focusing on clarity and helpfulness. Each error message should: 1. Briefly identify the issue in plain language (no code-like jargon or generic “Error 123”), 2. If possible, state a next step or solution for the user . For example, instead of “Invalid input”, say “Invalid email address format. Please enter a valid email (e.g., name@example.com).” Or if an upload fails due to size: “File is too large. Maximum upload size is 5MB – try a smaller file.” If the error cause is unknown or internal, still apologize or acknowledge: “Something went wrong on our end. Please try again or contact support if the issue persists.” The tone should match overall product (some use a bit of humor, but carefully). But most importantly, it should help the user recover or understand what to do next. If an action is available, mention it: “Please refresh the page.” or provide a Retry button. Avoid blame-y language (not “You did X wrong,” rather “Could not do X”). Also, avoid technical details that mean nothing to user (e.g., stack traces). If you have error codes for support, hide them or present in a user-friendly way (“Error 408 – request timed out. Check your internet connection.”). This output likely is a list of error scenarios (which might be derived from functional spec) each paired with the message to display. Possibly also variant if needed (some products have shorter error text on small spaces vs more detail in a tooltip). Good error messages significantly improve UX by reducing frustration and support calls, so this is an important part of design. • Accessibility review — contrast, keyboard, screen reader basics Key Points: An accessibility (a11y) review checks that the design can be used by people with disabilities or situational limitations. Key things to verify: Color contrast between text and background meets WCAG standards (generally 4.5:1 for normal text, 3:1 for large text). Ensure that color is not the only means of conveying information (e.g., an error field not just outlined in red, but also has an icon or text). Keyboard navigation: all interactive elements should be reachable and usable via keyboard alone (check that no control requires mouse hover to access key info, or if it does like a tooltip, there’s an alternative). This includes logical focus order in the layout (should follow reading order). Focus states: design should show visible focus indication for interactive elements (so if someone tabs through, they can see where they are). Screen reader: make sure important content has appropriate textual representation. That means images have alt text (or will have), icons if used as buttons have a label, headings are used consistently (for screen reader navigation by headings). Also consider dynamic content – if something like an error message appears, it should alert the screen reader (via ARIA live region perhaps). If any custom components are designed, consider their ARIA roles (like a custom dropdown needs ARIA role=“combobox” etc.). Also check target touch sizes for people with motor impairments (e.g., buttons not too small on mobile). The output of a review would be a list of issues or confirmations: e.g., “Contrast of light gray text on white fails, darken it.”, “Need to add focus outline to card component for keyboard nav.”, “All form fields have labels, good.”, “Ensure modals have focus trap and screen reader announced.” It’s a lot easier to address these at design time than retrofit later. This also aligns with legal and ethical requirements. So basically, run through the design with an accessibility checklist and note improvements needed. • /ux-a11y:audit [screens] — outputs a11y issues + fixes checklist Key Points: This yields a checklist of any accessibility issues found in the given screens and suggestions to fix them. For instance: Issue: Text on Button has contrast ratio 2.5:1 (too low) – Fix: use darker text color or larger font. Issue: Icon-only button for “Delete” – Fix: provide a visible label or aria-label. Issue: Missing skip navigation link on long page – Fix: add one for keyboard users. Issue: Form error message color is red only – Fix: add an error icon and text so color isn’t sole indicator. Issue: Modal close button not focusable – Fix: ensure it’s in tab order. The output would list each screen or component with any found issues and a recommended resolution. It might categorize by severity (critical: will block users with certain disability, vs minor). This checklist then guides designers and developers to address each item. It basically ensures compliance with at least basic WCAG AA guidelines. By having this, the team has clear action items to improve a11y before launch, rather than discovering them through complaints or audits later. • /ux-a11y:aria-notes [components] — outputs ARIA labels/roles guidance Key Points: This focuses on ARIA (Accessible Rich Internet Applications) attributes needed for custom components to be screen-reader accessible. If your design includes custom UI controls (like a fancy dropdown, accordion, tabs, etc.), native HTML might not convey their roles automatically to assistive tech. So ARIA roles and labels are needed. For example: “Dropdown component: use role=‘combobox’ on the container, role=‘option’ on list items, aria-expanded on trigger button, aria-activedescendant to highlight current item, etc. Also provide aria-label or aria-labelledby to describe the dropdown purpose.” Or “Modal dialog: add role=‘dialog’ and aria-modal=‘true’, ensure focus moves inside on open, give the dialog a label (via aria-labelledby pointing to the modal title element).” If there’s a progress bar, use aria-valuemin/max and aria-valuenow. If images have meaning, note to include alt text. If an icon button (like a trash can for delete), note it needs aria-label=“Delete”. Essentially any non-standard element, list how to make it accessible: roles, states (aria-pressed for toggle buttons, aria-selected for selected items), and how they update (e.g., if an element appears dynamically, maybe use aria-live for announcements). Also note any keyboard interactions (like arrow keys to navigate a carousel – need proper roles and focus management, and maybe instructions via aria-describedby if complex). This output becomes a guide for developers implementing the components to ensure screen reader users (and other AT users) can use them. It might be overkill to provide ARIA for standard HTML elements that already are semantic (like or etc., those don’t need extra ARIA, just correct usage). Focus on custom or non-semantics (divs acting like something). This ties into the component specs and dev notes – basically embedding accessibility instructions. Following these notes helps achieve compliance and inclusive design. • Onboarding experience — activation, guidance, first-run Key Points: Onboarding refers to the user’s initial experience with the product – how you guide new users to value quickly (often called activation). Designing onboarding might involve a sign-up flow, welcome screens, tooltips or coach-marks highlighting features, sample content, etc. The idea is to avoid dropping a user into a blank app with no guidance. Instead, you might have: a brief tour (maybe 3 screens or a short animated guide), or an interactive checklist (“Do these 3 steps to get started”), or contextual tips as the user explores for the first time. It’s also about driving the user to the “Aha moment” – e.g., in a task app, getting them to create their first task. Identify what key action correlates with long-term retention, and make sure onboarding encourages that. Activation metrics could be like “user completed profile” or “made first post.” The onboarding design should be welcoming and not overwhelming – don’t ask for too much upfront (minimize required fields to sign up, maybe use progressive profiling later). Possibly integrate some personalization (“Tell us your goal, we’ll tailor your experience”). Also, plan for tracking – so we can measure where users drop off in onboarding. The deliverable might be storyboard or flow of the first-run experience and any assets (illustrations, copy) needed. Also ensure it’s skippable or not annoyingly repetitive (maybe show tips only once, or allow “skip tour”). Keep consistency in visual style with main app. The onboarding should seamlessly lead into regular usage once done. • /ux-onboarding:steps [product] — outputs onboarding steps + activation event Key Points: This would outline a recommended onboarding flow for the product, step by step, and identify the key activation event (the moment user gets value or is considered activated). For example: 1. Account Creation – user signs up (maybe via email or OAuth). 2. Welcome Screen – greeting and what to do first. 3. Profile Setup (Optional) – user may set name, upload pic (can be skipped or done later to reduce friction). 4. Core Action Tutorial – e.g., a guided step to create first project or first note (with arrow/tooltips highlighting UI). 5. Secondary Feature Teaser – e.g., prompt to invite colleagues or try a premium feature (depending on strategy). 6. Completion – a “You’re all set!” message or checklist with ticks showing they finished onboarding. Also mention if using an in-app tour vs. separate screens vs. email onboarding drips. The activation event could be “User created first X” or “completed 3 key actions.” State that clearly: e.g., “Activation event: User creates and saves their first project. Our onboarding should drive users to achieve this as it’s highly correlated with retention.” Sometimes they choose an activation metric like “add 10 friends” (for social networks) or “made first 3 searches” etc. By identifying it, design and growth teams can focus on nudging users to do that action. The output might say “Goal: have user within first 5 minutes/day.” Each onboarding step then is framed to get them there. This also aligns teams on what to measure and optimize in onboarding. • /ux-onboarding:tooltips-copy [steps] — outputs tooltip/microcopy set Key Points: If the onboarding plan includes tooltips or in-app guidance, this command would produce the actual text for each tooltip and assign them to the steps. For example: Step 1: highlight “Create Project” button with tooltip: “Click here to create your first project.” Step 2: after they create one, highlight next feature “Great! Now invite your team using this button.” etc. Each tooltip microcopy should be short, friendly, and action-oriented. Possibly have a heading (“Step 1 of 3”) if multiple. Also maybe include a “Got it” or navigation control. If the steps are guided in sequence, mention if tooltips auto-advance or wait for user action. The microcopy should match the tone. Additionally, mention where the tooltip anchors (e.g., “Tooltip appears above the ‘+ Project’ button”). Ensure content is concise enough not to block UI or overwhelm (maybe ~40-60 characters each if possible). Also consider that some users may skip or close them, so ensure critical info is also available elsewhere if needed. The output would list something like: • Tooltip 1 (attached to X element): “Click New Task to add your first to-do.” • Tooltip 2 (attached to Y element): “Use Filters to see specific tasks. (Optional)” • etc. If visuals or arrows are needed, might note that too. Basically it’s delivering the content so that the devs/designers can implement those onboarding cues with the right messaging. Remember to be encouraging: e.g., “Nice! You did X, now try Y”. Possibly incorporate dynamic placeholders if needed (user name, etc.). This set ensures consistency and completeness of the first-run guidance content.

⸻

Engineering (Frontend/Backend/Mobile) • Technical discovery — feasibility, architecture, dependencies Key Points: Before diving into implementation, engineers perform technical discovery to understand feasibility of requirements, sketch a possible architecture, and identify any dependencies or risks. They review the PRD and ask: Is this doable with our current stack? Any new tech or libraries needed? How will components interact (high-level architecture diagram)? For example, if a feature needs real-time updates, feasibility might involve evaluating WebSocket vs polling. Dependencies might include needing a third-party API or needing another team’s service to provide data. This discovery phase often produces a brief report or at least notes: list of identified technical challenges (e.g., “We have no OCR capability; need to integrate a library”), decisions to be made (like “Will we store this data server-side or rely on client caching?”), and potential spike tasks (small experiments to test approach). The team might also estimate roughly the effort or complexity class now that approach is clearer. Technical discovery aligns everyone on how we might build it before committing to stories or tasks, reducing surprises later (like “Oh, this can’t scale” discovered late). It’s like a mini planning/architecture sprint that de-risks the implementation. Also, outputs include system diagrams or pseudo-code for critical flows, if helpful. Ultimately, this ensures the feature is technically thought through, not just UX-wise, and that it fits in our architecture without major issues. • /dev-discovery:feasibility-check [prd] — outputs risks, dependencies, unknowns Key Points: Given a PRD, this call would enumerate the technical risks, dependencies, and unknowns for building it. For example: • Risk: “Image upload feature may strain our server storage and bandwidth – need to assess if our infra can handle ~10MB uploads.” • Risk: “Performance on older devices might suffer due to heavy client-side encryption – might need optimization.” • Dependency: “Requires new endpoint from Payments service to validate coupon codes – dependency on Payments team, timeline needs sync.” • Dependency: “We rely on External API X for weather data – ensure their SLA is acceptable and plan caching in case of downtime.” • Unknown: “Algorithm accuracy for recommendation – unclear if existing data is enough; may need data science input or a trial.” • Unknown: “Exact scaling requirements not specified – if user base 10x, will current design hold? Need clarification on expected volumes.” Essentially list things that could impact success or require coordination. The output would also possibly suggest mitigation: e.g., for each risk how to reduce it (maybe a spike or fallback plan). Highlighting these early means PMs or management can make informed decisions (e.g., maybe we do smaller scope if risk too high, or allocate more time). It’s basically a sanity check. If this list has huge blockers, might escalate to stakeholders to adjust requirements or schedule. Usually, after this, trivial unknowns become known after short investigation, dependencies result in tasks to talk to those teams, etc. The result is a team aware of the main technical challenges before coding. • /dev-arch:proposal [feature] — outputs architecture outline + choices Key Points: This generates an architecture proposal for a new feature – describing how the feature will be implemented in terms of system components. It might include: • Diagram or description of components and data flow: e.g., client app -> our API -> database; or new microservice interactions if needed. • Key modules or layers: e.g., “Add a new service for handling video processing, use message queue between web app and this service for asynchronous processing.” • Technology choices: e.g., “We propose using PostgreSQL for the new logging store, as we already use it and the data fits relational model.” Or “We will use Redis to cache the results for performance.” If multiple options exist, mention them and why one is chosen (like SQL vs NoSQL, or use existing library vs build custom). • Design patterns to apply: e.g., “Using a pub/sub pattern for notifying other parts of the system about this event,” or “Follow MVC where new model X is created”. • Consider scalability and reliability: e.g., “We’ll containerize the new service, auto-scale based on queue length.”, “We plan read-replicas for DB if read traffic high.” • Note any APIs or interfaces introduced: e.g., “New REST endpoint POST /api/v1/project will be created, internal call to Auth service for user validation.” • Security or compliance: e.g., “Encrypt sensitive fields at rest using AES.” • Outline error handling across components. • Mention how it fits with current architecture (reusing authentication system, logging, monitoring). • Identify any new dependencies (like adopting a new open-source library or cloud service). • Rough idea of data models / schemas changes if any. The proposal should be discussed with the team for feedback. It’s typically not super low-level (not code design, but component design). The output would be like a high-level tech spec that engineers can refine into tasks. Also it might mention things like “Option A vs B: chosen A because easier integration, though B might be faster – we accept small perf hit for dev simplicity.” That shows thought in decisions. All in all, it’s a blueprint to ensure everyone agrees on the approach and catches flaws before building. • APIs + data contracts — schemas, versioning, ownership Key Points: If the feature requires new APIs (internal or external), define the API contracts clearly. This includes the request/response format (data schema), HTTP method & endpoint (if REST) or query/mutation if GraphQL, etc. For example, define JSON fields, their types, which are required/optional. Also consider versioning strategy: if this is a new endpoint, start at v1; if modifying an existing one, do we version bump or make backward-compatible changes? Also, define who “owns” the API – e.g., if it’s cross-team, make sure the responsible team is aware. Data contracts also cover events or messages if using queues (schema of event payload). Ensure consistency with existing conventions (naming, error codes). This documentation will later be used by frontend devs or external integrators to know how to use the API. Also, note any rate limits or auth needed. Essentially, treat API design as a product: design the endpoints to be intuitive and minimal. Getting contract right is crucial as changes later can break clients. So review them with stakeholders/consumers early. If working with third parties, possibly prepare an API spec doc or OpenAPI file. Confirm how changes will be communicated (like add fields in backward compatible way ideally). Good data contract design can prevent a lot of integration issues and ensures everyone knows what data flows where. • /dev-api:contract-draft [entities] — outputs endpoints + request/response schema Key Points: This will output a draft specification for API endpoints related to the given entities. For example, if the feature involves a new “Project” entity, it might list endpoints like: • GET /api/v1/projects – Returns list of projects. Response schema: array of project objects (then list fields like id, name, createdDate, etc.). Possibly mention filters or pagination if needed (e.g., accepts query params page, pageSize). • POST /api/v1/projects – Create project. Request body schema: e.g., JSON with name (string, required), description (string, optional). Response: 201 Created with project object (or at least new id). • GET /api/v1/projects/{projectId} – details. Response: project object or 404 if not found. • PUT /api/v1/projects/{projectId} – update. Request: fields to update (and note partial vs full update semantics). Response: updated object. • DELETE /api/v1/projects/{projectId} – delete. Response: perhaps 204 No Content on success. Also specify error responses format (like a standard error JSON with code and message). The schema details each field, type, any constraints (like max length). This draft can be reviewed by front-end devs to ensure it meets their needs (maybe they need an include param or something). If there’s multiple related entities, include those as needed. Also if websockets or push events, spec those payloads. We should also mention authentication (e.g., requires Authorization header with token) and any specific permissions (like only owner can update project). The draft is basically an API reference in text form. It might be close to what you’d put in an API documentation or an OpenAPI spec. For versioning, you might incorporate a version in URL as shown or say we add new fields in responses so old clients are still okay. This ensures back and front devs (and testers) all are in sync on what’s expected to send/receive. • /dev-api:versioning-plan [api] — outputs compatibility + migration notes Key Points: If the feature changes existing APIs or if new APIs might evolve, outline a plan for versioning. For example: “We will introduce these changes in v2 of the API while keeping v1 for backward compatibility for 3 months.” Or “We’ll do a non-breaking expansion of v1: adding new optional fields in the response that old clients will ignore, so version bump not needed.” If completely replacing an API, describe how to deprecate the old one (e.g., “Mark /v1/projects as deprecated in docs, stop support after June 1”). If internal microservice API changes, maybe it’s just coordinate with consumers but still note how you ensure compatibility (like deploy new version that handles both old and new messages during transition). Provide any migration steps: e.g., “Migrate database schema from old to new field gradually: deploy code that writes to both old and new fields, then migrate data, then read from new field once stable (parallel run for safety).” Or “Clients must switch to /v2 by next quarter; we’ll monitor usage of /v1.” Possibly even a timeline. Also ensure versioning for data like if storing new records differently. Include how versioning is indicated (URL vs header vs content negotiation). If dealing with mobile app APIs, you might have to support multiple app versions concurrently – so how do you handle an old app calling an updated server? (Often by leaving old endpoints in place, or checking app version in requests). The plan ensures no sudden breakage in production and gives teams clarity on how changes are rolled out. This output might be quite textual but important for release planning. • Frontend implementation — UI, edge states, performance Key Points: Frontend engineers will implement the UI according to designs, ensuring it’s not only pixel-perfect but also handles all those edge cases and maintains good performance. They need to cover: building components (possibly reusing design system ones or building new ones per spec), implementing state management and logic for user interactions, calling APIs and handling responses (loading spinners, error messages as per design), updating the UI based on different states (empty, etc.). They also consider responsiveness (mobile vs desktop, etc., unless separate mobile dev team if native). They need to test it across supported browsers. Also optimize for performance: lazy load heavy content, avoid re-render bottlenecks, optimize bundle size (maybe code-splitting if needed for large feature). Accessibility implementation is crucial on front (ARIA, keyboard support as per notes). They may need to coordinate with backend on any API adjustments as they integrate. Caching maybe if needed (like caching requests or using local storage where appropriate). Also possibly instrumentation for analytics (logging certain user events). A good FE implementation means the feature not only looks right but feels smooth and robust to user input (no crashes on unexpected input, etc.). Possibly they write unit tests for components and integration tests for flows. Essentially, the FE brings the UX to life in the browser/app. It’s important they follow the acceptance criteria and refer back to PRD for any logic. Also they should think about internationalization if relevant (ensuring UI works with long text, etc.). And security on front-end (not exposing secrets, using proper sanitation for any user-generated content to avoid XSS). • /dev-fe:task-breakdown [ux-handoff] — outputs FE tasks + estimates bands Key Points: This takes the UX/design handoff (which might include all screens and states) and breaks down the frontend development work into tasks, possibly with rough size/complexity estimates. For example: • Task 1: Implement Project List Page UI – includes layout, fetch projects API integration, loading and error states. Estimate: 3 days (M). • Task 2: Implement Project Create Modal component – form fields, validation, submission to API, success handling (redirect). Estimate: 2 days (S). • Task 3: Project Details Page – display data, implement subcomponents (like tasks list), hook up editing inline. Estimate: 4 days (L). • Task 4: Shared Components – e.g., a date picker or tag input if new, which will be reused in multiple places. Estimate: 3 days (M). • Task 5: State Management – set up Redux store for projects (or using context, etc.), actions for loading and caching. Estimate: 2 days (S). • Task 6: Responsive adjustments – ensure mobile layout, test breakpoints. Estimate: 1 day (S). • Task 7: Testing & bugfix – write unit tests for components, integration test for major flows, cross-browser tests. Estimate: 2 days (M). • etc. Each task might reference specific parts of design or PRD items. The estimates might not be absolute precise but maybe t-shirt sizes or a range (Small ~1-2 days, Medium ~3-4, Large ~5+). If multiple devs, might note who takes what or which tasks depend on others (e.g., need API ready first perhaps). This breakdown helps project planning (the PM can see if timeline fits) and ensures no part of the UI is forgotten. It also clarifies scope to avoid creeping beyond what’s needed. Possibly identify any tasks to spike or research (like “Investigate using library X for chart - 0.5 day”). Also tasks to implement analytics events if required by growth. The deliverable is basically a list, which could become JIRA tickets or similar. It aids in sprint planning and allows the dev to communicate complexity up front (maybe “the date picker is tricky, might actually be L rather than M if customizing a lot”). Everyone then has a clear view of FE work ahead. • /dev-fe:state-machine [screen] — outputs UI states + transitions Key Points: For a complex interactive UI, a state machine diagram/description can be helpful. It enumerates the various states a component or screen can be in, and events that transition between states. For example, consider a multi-step form: • States: Step1 (idle or filled), Step2, Confirmation, Error. • Transitions: from Step1 (on Next button click if validation passes) -> Step2; from any step (on Cancel) -> Cancel confirmation or exit; on submission -> either Confirmation state or Error state if server fails. Or consider a toggle switch component: states {On, Off, Disabled}; events: user click toggles On<->Off (if not disabled). For something like an image uploader: states: Idle (no file), Preview (file selected), Uploading (progress), Success, Error; transitions: Idle -> Preview (on file chosen), Preview -> Uploading (on user hits upload), Uploading -> Success (on server OK) or Uploading -> Error (on fail, with possible retry back to Uploading). Outlining these ensures the UI code covers each properly and knows how to transition without glitch. The output might be a simple diagram or a table of “State X: events and next state”. This is particularly valuable to avoid weird edge issues (like what if user double-clicks? state machine might handle by ignoring events in certain states). Also, having this can make implementing via frameworks (like using XState for React, as an example) easier or at least conceptually clear. It’s basically formalizing what was partially in PRD (acceptance criteria) and design (states), but from an implementation perspective – focusing on logic and sequence. This ensures the FE dev doesn’t miss a transition or get stuck in an undefined state. • Backend implementation — services, storage, scaling, reliability Key Points: Backend engineers will build the server-side components: the APIs, business logic, database interactions, and any new services. They need to design database schema changes or new collections/tables for the feature, ensuring data integrity and indices for performance. Implement any new service (maybe a microservice) if the architecture calls for it. They will consider transactionality (if two related things must succeed together), and if distributed, maybe using message queues for asynchronous parts. They must enforce security on the backend: authentication checks on each endpoint, proper input validation (not trusting the client). Also apply rate limiting or other abuse prevention if necessary. Logging and monitoring should be added around new code (so issues can be detected). Consider how to scale the new feature: e.g., if it’s memory or CPU intensive, perhaps vertical/horizontal scaling, or using caches. Also plan for reliability: graceful error handling (don’t crash the whole app), perhaps retries on external calls, and fallback paths. If feature is critical, maybe ensure redundancy (like replicate data or have backup service). They also might need to set up configuration flags or toggles if doing a staged rollout. Tests: they should write unit tests for logic, and integration tests for data layer, maybe contract tests for APIs. Also ensure backward compatibility with old data or calls if applicable. Migration scripts if altering DB significantly. Essentially, BE ensures that under the hood, everything is robust and can handle the expected load and beyond, and that operations (devops) are aware of any changes (like new environment variables, cron jobs, etc.). If there are cross-team integration (like calling another team’s API), coordinate that. And document any new API for front-end or third parties as needed (maybe update API docs). Ultimately, backend implements the heavy lifting so the front-end gets the data it needs reliably. • /dev-be:task-breakdown [prd] — outputs BE tasks + data model notes Key Points: Similar to the FE breakdown, list out backend tasks: • Task A: Design DB schema for new feature (e.g., create table Projects with columns … including keys and indexes). Output: migration script. Estimate: M. • Task B: Implement API endpoints (list each: GET /projects, POST /projects, etc.). Could split into separate tasks if large: maybe one for read endpoints, one for write endpoints. Estimate: L. • Task C: Business logic layer – e.g., implement ProjectService class with methods for creating projects (including validation and sending welcome email maybe). Estimate: M. • Task D: Integration with external service X if any (e.g., call payment API for billing). Estimate: M (because need to test thoroughly). • Task E: Background job (if the feature requires asynchronous processing or scheduled tasks). Estimate: S. • Task F: Authentication/permissions – update auth rules (like ensure only certain roles can access something). Estimate: S. • Task G: Write tests (unit tests for service, endpoint tests perhaps using test framework, maybe a test seeding some data and calling API). Estimate: M. • Task H: Documentation & config – update API docs or internal README for new setup, add any config toggles with defaults. Estimate: S. • Task I: Deploy & Migration – plan and run the DB migration on staging/prod, coordinate deployment (maybe doing a feature flag or handling partial data). Estimate: not coding time but included in plan. Possibly also tasks for performance tuning (like load test if needed after basic working). Each with an owner if multiple devs. Also highlight any sequence needed (like DB migration must run before deploying code that uses the new table). Data model notes: e.g., “Project table will have foreign key to User (owner). Ensure to set cascade delete if user removed OR maybe decide not to allow user removal if projects exist, etc.” Could also note “We should index project_name for search, but might be fine without initially if usage low.” Or “We’ll use existing table X and just add new column Y.” That one requires noting migration with default etc. The breakdown clarifies tasks for planning sprints and ensures no part of backend is missed (like often folks forget to schedule backup/monitoring for new table – maybe tasks to update monitoring dashboards for new error logs). Also could include “Security review tasks” if needed (like run static analysis or get pen-test on new endpoint). This way, PM/lead can see timeline (if sum of tasks looks large, maybe adjust scope). It’s also a sort of checklist for code review later (“did we cover all tasks?”). Overall, a thorough breakdown sets backend dev work expectations clearly. • /dev-be:data-model [entities] — outputs tables/collections + constraints Key Points: This details the data model for the new feature – essentially, define the database schema or data structures. For each entity: • If relational DB: define tables with columns, data types, primary keys, foreign keys, and any constraints (unique, not null, check constraints). E.g., Table Projects: id (PK, uuid), name (varchar(100), not null), owner_id (FK to Users.id), created_at (timestamp), … Constraint: unique (owner_id, name) perhaps if we want unique project names per user. Indexes: index on owner_id for quick lookup. • If using NoSQL or an object store: define the collection and sample document structure or fields. E.g., Collection “projects”: each document has id, name, ownerId, tasks (array of sub-documents with …). Mention if some fields are indexed or if it’s partitioned by some key. • Any special fields: e.g., a JSON field or array if using Postgres JSONB or others. • If applicable, mention how to enforce relations or cascade deletes, etc. Or if using an ORM, mention any model class relationships (one-to-many between User and Projects). • Also consider data retention if needed (like log tables might prune after 30 days). • If an existing table is extended: mention the new columns and default values, etc. • If any domain constraints: e.g., “status” field can only be ‘new’,‘active’,‘done’. • Show a quick ER diagram or just textually describe relationships between entities: e.g., “A Project has many Tasks, each Task has a project_id FK. A User can belong to many Projects through a join table project_members”. • Also consider how this model scales: e.g., if tasks can be large, maybe tasks in separate table vs embedded – justify the approach. • Include any constraint about transactions: e.g., if creating a project also creates default tasks, how to ensure atomicity (maybe through transaction if same DB, or eventual consistency if using separate stores). • If using microservices with separate DBs, mention that (like “Project service will store projects in its own DB, and we replicate some data to other service via events if needed”). • Data model should align with product logic: e.g., if we need to query projects by deadline often, consider indexing deadline. • Also mention any seed or default data that will be inserted (like default roles or something). • If caching layers or search indices are part of model, mention how they map (like “we will also index project in Elasticsearch by name for search”). • If diagramming: show connections like Project -> User (owner) [1:many]. • This document helps everyone (including QA writing queries, etc.) to understand the data behind the scenes. It’s critical for ensuring we didn’t miss a needed field or that we properly design for things like deletion (if user deletes a project, tasks should ideally be deleted or orphan? define cascade). • It also will be referenced in code in migration files etc. And possibly used for writing direct SQL if needed (like some complex report). Summing up, it’s a blueprint of how data for new feature is structured and maintained, which is foundational to correct and efficient backend operation. • Integrations — payments, notifications, third parties Key Points: Many features require integrating with external systems or services (e.g., a payment gateway, an email/SMS service for notifications, a mapping API, etc.). For each integration, engineering must plan: • How to connect (library or direct API calls? which protocol?). • Authentication/keys management (e.g., store API keys in config/secret store). • Data format conversion (e.g., our system -> 3rd party request). • Error handling strategy (what if the third-party is down or returns error? do we retry, queue for later, or show user a message?). • Performance considerations (calls could be slow; perhaps make them async or batch them). • If needed, abide by their rate limits or quotas (maybe we need to throttle requests). • Testing approach: often stub the external service in dev/test environments or use a sandbox environment if provided. Possibly write integration tests hitting a sandbox if safe. • Logging for these calls (for debugging issues with third-party). • Security: ensure data we send is minimal and safe, and we handle their responses properly (validate fields, avoid injection if they send something malformatted). • If multiple environments (dev/staging/prod) need separate credentials or endpoints, manage that. • If the integration is two-way (like webhooks from the third-party to us), implement receiving logic, verify signatures if any, and handle idempotency if needed (webhooks can repeat). • Also, plan for any necessary agreements or compliance (like connecting to a bank API might have compliance tasks). • Document usage of the integration for others (like “we use Stripe for payments: see config in … and how to simulate payments…”). • Possibly implement a wrapper in our code to abstract the external API, making it easier to swap if needed or to centralize error handling. • If costs are associated (pay per use), maybe include measures to avoid unnecessary calls. • If using open source libraries for integration, check their license and keep an eye on versions for updates. Essentially, integration tasks ensure the external piece works smoothly as part of our feature, without causing fragility to our system. It’s often one of the riskier parts because we can’t control external uptime or behavior, so we have to code defensively and monitor integration specifically (like alert if external call failures spike). The dev assigned might need to read through third-party docs thoroughly and perhaps do a quick proof-of-concept to confirm it works as expected. • /dev-integration:plan [provider] [use-case] — outputs API calls, retries, failure modes Key Points: This outlines how we’ll integrate with a specific external provider for a certain use-case, covering details like: • API calls to be made: list each endpoint of the provider we will call, with method (GET/POST etc.) and data. For example: “Use Stripe API – Create customer (POST /v1/customers) when user adds payment info; Charge customer (POST /v1/charges) when purchase made.” Or for notifications: “Use Twilio API: send SMS via POST /Messages endpoint for phone verification codes.” • Specify sequence if multiple calls: e.g., first create transaction then confirm etc. • Retries: If a call fails (network error or 5xx from provider), how will we handle? Perhaps “Retry up to 3 times with exponential backoff for transient errors.” Or “If sending email fails, log error and schedule a retry job to attempt again in 5 minutes, up to 5 attempts.” Some providers have idempotency keys to avoid duplicates on retries – mention using those if applicable. • Failure modes: What if the external service is down or consistently failing? • If it’s critical (like payment), possibly block the user action and show error “Payment service unavailable, try later.” • If less critical (like sending analytics), maybe just log and move on. • If partial failures are possible, define how to compensate (like charge succeeded but confirmation email fail: we can try email later). • Worst case scenario handling: e.g., if Twilio down, allow user to register without phone verify but mark them for later verification. • Also mention timeouts (like “we will use 10s timeout for API call to prevent hanging our thread”). • Throttling: If we need to avoid hitting provider’s rate limit, mention using a queue or delaying non-urgent calls (like bulk notifications, maybe send 1 per second). • Security aspects: like “All calls use TLS, ensure to verify TLS certificate (should be by default). Use provider’s SDK if available for robust handling.” • If provider returns error responses, outline example error codes and how we map them to user-friendly messages or actions. e.g., “If payment API returns card_declined, show user ‘Card was declined, try another payment method.’ If returns insufficient_funds, instruct them accordingly.” • If applicable, describe fallback: e.g., use a secondary provider if primary fails (some systems do multi-provider failover for SMS or email). • Logging/alerting: e.g., “If error from provider, log error with code. If >=5% of calls in a 10min fail, trigger alert to on-call as it may indicate outage.” • This plan ensures reliability and resilience in integration. It basically says, “Here is exactly how we’ll call X, and here is what we’ll do when it doesn’t work as expected.” This is often overlooked until something breaks, so planning ahead is great. • Also mention if provider API usage need tracking for costs (like keep track of SMS count). • If asynchronous flows (like we call and get a callback later), detail that as well. So after reading this, one should understand how our system will behave when the external integration is smooth and when it’s rocky, minimizing user impact and keeping our system stable. • /dev-integration:mock-stubs [provider] — outputs stub interfaces + fake responses Key Points: During development and testing, we often don’t want to hit the real external service (due to cost, unpredictability, or unavailability offline). So we create mocks or stubs for that provider’s API. • The plan might describe adding an interface or wrapper class around the provider’s API calls (like PaymentGateway interface with a method charge(amount, token)), and then having two implementations: RealPaymentGateway (calls Stripe) and MockPaymentGateway (fakes it). • Or using dependency injection or a flag to use a dummy service in dev/test environment. For example, in dev config: USE_FAKE_SMS_SERVICE=true which makes all SMS sends just log to console or store in memory list. • Outline what fake responses should look like: e.g., for a charge request, fake response can mimic success JSON of Stripe but with dummy IDs. Or for error simulation, maybe allow triggering specific errors via certain test inputs (like if amount = $0.99, treat it as simulate decline). • If using recorded responses, maybe plan to use VCR (in testing) or static JSON files to simulate. • If the provider has a sandbox environment, note usage of that in testing (which might be better than a fully fake, as it exercises code more realistically but still safe). • For unit tests, mention using mocking frameworks to stub HTTP calls. Possibly provide an example: e.g., “We will use WebMock to intercept calls to api.twilio.com and return a preset success XML for tests.” • If integrating with CI, ensure no real calls (so maybe environment variables for test contain fake keys pointing to sandbox, or code automatically fakes out). • Also mention that these stubs should cover various scenarios: e.g., success, and a few error cases to test our error handling logic. • Good practice: ensure devs can run the app fully offline with fakes (so they can demo UI flows without internet, etc.) • In summary, define how to abstract the integration and provide dummy implementations for dev/test. Possibly also used for front-end if front-end wants to test UI without real backend (like stub responses via MSW or similar). • Emphasize that the interface of stub should match real one so switching is seamless. Document how to switch (maybe config file). • This kind of planning ensures we won’t accidentally send test transactions to production gateway or vice versa, and helps maintain good test coverage without external dependencies. So, after this, the team will implement those stubs and use them accordingly, which speeds dev cycle and allows testing edge cases that might be hard to trigger on real system. • CI/CD setup — automate build/test/deploy Key Points: Set up or update continuous integration pipeline to incorporate this feature’s build and testing: • Ensure any new modules or packages are included in the build process (e.g., if we added a new microservice repository or new environment variables needed by build). • Write new tests and have them run in CI (unit tests, integration tests) and ensure any required services are available in CI (maybe use Docker containers for a test DB or stub). • Perhaps create new pipeline steps: e.g., if we introduced front-end build for a new app, add that to CI. Or if we have to run a security scan or lint on new code, ensure the pipeline will catch failures. • Also, continuous deployment (if we have it): configure so that merging this feature’s code triggers deployment to staging environment and eventually production (maybe behind a feature flag). • If multiple components need coordinating (like deploy backend first, then front-end), plan that order or decouple via backward compatibility. • Possibly add a new job to pipeline for building a Docker image of a new service, push to registry. • Add any environment-specific tasks (migrations running automatically? or do we run them manually as part of deploy? clarify). • Make sure pipeline secrets cover whatever is needed for integration tests (like dummy API keys). • Also incorporate code quality checks: maybe new ESLint rules, or track coverage and ensure it doesn’t drop below threshold after adding tests for new code. • If using feature flags, ensure pipeline can deploy code dark (with flag off) and then we can toggle on. • If needed, update infrastructure-as-code scripts (Terraform, etc.) to include new resources (like new database or queue). • Essentially ensure that from pushing code to code running in environment is as smooth and automated as before, if not more. • Outline any manual steps that remain for release (maybe none if fully CD). • If planning canary or phased rollout, mention how pipeline supports that (like separate stage to deploy to 10% servers). • Also consider rollback: if feature causes issues, is our deploy process capable of quick rollback? If feature includes a DB migration that isn’t backward-compatible, plan how to handle (maybe initial deployment includes code to handle both old and new field, then second deploy toggles usage). • Document these changes for DevOps team or in README so everyone knows how to deploy/test going forward. • Possibly add monitors or health checks to CI (like after deploy, run a smoke test to verify new endpoints responding). • The result is no surprises on release day - everything is integrated into our normal devops flow. • /dev-cicd:checklist [repo] — outputs pipeline steps + required gates Key Points: This enumerates the CI/CD pipeline for a given code repository or project, highlighting each step and any gating conditions (like approvals or tests passing). • For example: Build step – compile code or Docker build. Gate: fails if compilation fails or if any linter errors. • Then Unit Test step – run tests, Gate: require 100% tests pass (and maybe coverage threshold). • Then Integration Test step (maybe deploying to ephemeral container or using in-memory DB) – Gate: they all must pass. • Possibly Static Analysis/Security Scan – Gate: no high vulnerabilities or code smells allowed. • Artifact packaging – e.g., build Docker image or jar file, push to registry. Gate: only do if previous steps green. • Deploy to Staging – perhaps automatic if on main branch. Gate: maybe manual approval to push to staging if needed (or auto). • After staging deploy, Acceptance Tests or smoke tests on staging – Gate: must pass to proceed. • Code review (though usually manual outside pipeline, but you could mention branch protection requiring reviews). • Manual approval step for production deploy (some pipelines have a hold that a lead or QA must approve). • Deploy to Production – with details if it’s rolling, blue-green, etc. Gate: might check if during approved maintenance window or if feature flag toggled appropriately. • After prod deploy, perhaps run a quick smoke test or monitor gates (like pipeline monitors error rate for a few minutes, if too high, auto-rollback). • If something fails at a gate, mention what happens (e.g., pipeline halts and notifications sent to team). • If there are parallel steps, mention them (like run front-end and back-end tests in parallel for speed). • Also note any environment-specific differences (like test environment uses sqlite but prod uses Postgres – ideally not, but if so mention). • If there’s a separate pipeline for PRs vs main branch, describe differences (PR pipeline might just build and test, main pipeline goes through deploy). • Also mention any Quality gates thresholds – e.g., SonarQube must not exceed 5% new tech debt, etc., or coverage must not drop. • Finally, triggers: e.g., pipeline triggers on push to certain branches, or nightly, etc. • This acts as a checklist to ensure the pipeline covers all needed tasks and team is aware of gating criteria (so nobody bypasses e.g., not merging until pipeline green). • Also consider compliance: e.g., require 2 reviewers and pipeline passing before merge if that’s needed for certs. • The output could be bullet points or a flow diagram of pipeline. It’s helpful for new team members to understand the process, and for planning if new steps needed for the feature (like adding new test stage). • /dev-cicd:env-matrix [apps] — outputs envs, secrets, config map Key Points: Modern apps have multiple environments (dev, test, staging, prod, etc.) and require various configuration values and secrets. This matrix would list: • The environments we maintain (and maybe their purpose): e.g., Local Dev, CI/Test, Staging, Production (maybe also Demo or UAT if relevant). • For each environment, list important configuration differences: • e.g., Database URL (local uses localhost, test uses an in-memory or a test DB, staging/prod use real RDS instances with different names). • API endpoints for external services (maybe use sandbox endpoints in staging, real ones in prod). • Secrets: API keys, tokens (like Stripe test key vs Stripe live key, etc.). Possibly referencing how they are stored (in environment variables, or a secret manager). • Feature flags: some features might be enabled in staging but off in prod until launch, list those and their default values per env. • Logging level (debug on dev, info on prod). • Scaling config: maybe local is single instance, staging smaller scale, prod full scale cluster. • Third-party integration toggles: e.g., emails – maybe in test env we don’t actually send emails but just log them. • Data: e.g., use dummy payment provider in test, real in prod. • User accounts: e.g., admin logins might differ or test accounts exist on staging. • A config map could mean the key-value config items and environment-specific values. • Ensure secrets are not hard-coded anywhere – so how do we inject them? (like via CI/CD secrets or vault, etc.). This doc might not list actual secret values (for security) but rather secret names and where to find them. For example: “StripeSecret: stored in Azure KeyVault under key ‘stripe_secret{env}’”. • If using Docker or Kubernetes, mention if environment differences are handled via env vars or config files. • Also note any config that must remain consistent (like you shouldn’t point staging to prod database by mistake – so list DB per env clearly). • The matrix might be a table with rows as config items and columns as env, or sections by env. • This is very helpful to onboard devs or devops to know what’s needed to set up a new env or troubleshoot differences. • Also ensures that when deploying to each env we have the right values (so we don’t, for example, accidentally use test API key in prod). • It might also highlight which environments are deployed automatically vs manually. • If there’s any environment special considerations (like in staging, we regularly refresh data from prod or something), mention that. • This can serve as documentation but also as planning: for our new feature, we might need new config values (like a new API key for a new service). We need to procure them for each env and put them in the right place. • By listing it, we ensure no environment is forgotten (like if we have a performance test environment, do we configure the feature there too?). Summing up, after this, the team should have all config differences enumerated, so no “it worked in staging but not prod because config X was missing” surprises. • Monitoring hooks — logs/metrics/traces instrumentation support Key Points: It’s important to observe the feature in production. Plan what logging and metrics to add: • Logs: Identify key events to log. For example, when a main action happens (user creates a project, payment fails, etc.), log an INFO or WARN entry with relevant details (not PII though). If errors occur, ensure they log error messages and stack traces appropriately. Perhaps add logs at debug level for tricky parts to aid future debugging (but not overwhelm normally). Also structure logs (JSON format or with key-value contexts) so they can be parsed by logging systems (Splunk, ELK, etc.). • Metrics: Decide on counters, gauges, timings to record. E.g., count “projects_created_total”, measure “external_api_response_time_ms” for integration calls, track “featureX_success_rate”. Use whatever monitoring tool (StatsD, Prometheus, CloudWatch) to emit metrics. If new, define metric names, tags, and add instrumentation in code. Make sure to cover performance-critical segments (maybe measure DB query time for new query). • Possibly set up dashboards or at least note to update dashboards with new metrics. E.g., add “Project creation count” to business metrics board. • Traces: If using distributed tracing (like OpenTelemetry, Zipkin, etc.), ensure new code is instrumented with spans. E.g., wrap external API call in a span named “ThirdPartyAPI X call”, so if requests are slow, we see where. If microservices are used, ensure propagation of trace IDs through them. Possibly annotate spans with key data (like projectId on certain operations). • If not using a fancy tracing, at least ensure correlation IDs or something flows (like request ID from front-end to back-end to logs). • Alerts: Suggest any new alerts to set. For instance, “if new API error rate >5% for 5 minutes, alert dev team”. Or “if avg response time on new endpoint > 2s, create a performance alert”. List what thresholds might indicate problems. • Also if feature uses a queue or background job, monitor queue length or job failures. • Consider capacity: maybe add metric for memory usage if new process heavy, or track how many emails sent to watch cost usage. • If using an APM (application performance monitoring), maybe ensure new endpoints and queries show up properly (like name transactions well). • Summarize these “hooks” so ops knows to look for them and ensure they’re collected. Possibly coordinate with SRE to create new dashboards or integrate metrics into existing ones. • If there’s compliance monitoring (like audit logs for security), ensure feature logs those events (like admin actions). • This planning ensures that once live, we can answer “Is feature X being used as expected? Are errors happening? How’s the response time?” quickly via monitoring, rather than flying blind. • It also helps diagnosing user issues (we can search logs by user ID if logs cover needed context). • Plan to double-check logging doesn’t inadvertently log sensitive data though. • Possibly also note front-end monitoring if any (like capture JS errors or user metrics via something like Sentry or GA). • /dev-observability:events [feature] — outputs log fields + metric names Key Points: This would list specific events or actions within the feature that we will make observable via logs or metrics. For example: • Log events: “ProjectCreated” – Log at INFO with fields: user_id, project_id, project_name, timestamp. This way we can later find how many projects created or debug user issues. • “ProjectCreationFailed” – Log at ERROR with user_id, error_message, maybe validation errors etc. • “ExternalAPICall” – Log DEBUG each time we call external service X with fields: correlation_id, endpoint name, response_status, latency. • For each log, detail fields/structure: maybe provide a sample log line or JSON. Eg: { "level": "INFO", "event": "ProjectCreated", "user": 123, "project": 456, "name": "Test Project", "time_ms": 34 }. • Metric names: define metrics like: • feature_project_create_count (counter increments when project created). • feature_project_create_fail_count (counter). • feature_project_create_duration_ms (histogram/timer from user request to saved to DB). • thirdparty_serviceX_latency_ms (timer). • thirdparty_serviceX_errors (counter for error responses). • If using tags/labels, mention them e.g., label by error type maybe. • If using a service like Prometheus, write how the metric will be named (often snake_case), and maybe unit or type (counter, gauge). If Datadog, maybe dot notation like feature.project.create.count. • Also trace events if relevant: e.g., “Define trace span ‘ProjectSaveDB’ for DB operation”. • It’s useful to explicitly name these so dev and ops know what to look for or create on monitoring. It also ensures consistency (e.g., all new metrics prefixed similarly). • Possibly also mention any unique IDs to track flows, e.g., log correlation: a request_id field on all logs through one request to tie together. • If front-end logs events (maybe to analytics: “ProjectCreated” event to Mixpanel or so), list those names too (for product analytics). • Also consider user analytics metrics if needed (like daily active usage of feature, maybe to count how many did X – sometimes separate system or can derive from logs). • With this list, it’s easier to implement, because the developer can copy these names directly and avoid guesswork. And the SRE/analyst can pre-create dashboards or queries expecting these names. • It also helps code reviewers to ensure code has the promised logs/metrics. • Summaries: basically a dictionary of all observability outputs that feature will generate, bridging dev and ops. • /dev-observability:alert-rules [service] — outputs suggested alerts + thresholds Key Points: Based on the new feature or service, propose some alerting rules: • For performance: e.g., “Alert if 95th percentile response time of Project Create API > 1s for 5 minutes”. • For errors: “Alert if error rate of any new endpoint > 2% in 10 min”. • For service health: if a new microservice, “Alert if service down/unreachable (no heartbeats or HTTP 5xx rate > X)”, or CPU > 80% for sustained period if critical piece. • External integration: “Alert if external API failures > 5/min” or “if SMS send failures > 3 in 5m, maybe Twilio is down”. • Resource: if feature uses a queue or DB table heavily, “Alert if queue backlog > 1000 jobs”, or “if DB connections > 90% usage”. • Security: maybe “Alert on 5 failed admin actions in row” to catch potential misuse (depending on feature). • Thresholds should be sensible not to spam: likely glean from staging or initial run to calibrate. But for initial, we guess. Possibly note to adjust after seeing baseline. • If existing monitors cover some (like overall error rate for whole app), maybe just ensure new errors count into it. But if feature is isolated, set specific ones. • Also consider user-impact alerts: e.g., “No projects created in an hour during peak time might indicate something broken” (if unlikely to drop to zero). • Possibly an alert for too high usage too (like if suspicious huge spike, maybe a bug causing loop). • Provide the conditions (like percent or absolute counts) and time window, and severity (like warning vs critical). • These will be implemented in monitoring system (like Nagios, Datadog, CloudWatch Alarms, etc.) by SRE or dev with access. Listing them ensures it gets done and no scenario is overlooked (like maybe testers wouldn’t catch scaling issues, but alert will). • Some alerts might be temporary around launch (like alert if any error in new path, to catch early issues, can relax threshold after stable). • If we have on-call rotation, define which team or channel these alerts go to (maybe default dev team). • Aim to avoid false positives (maybe use a short window for critical stuff, or requiring multiple intervals). • The output is typically a list like: • “CRITICAL if ProjectService 5xx errors > 50 in 5 min”. • “WARNING if /api/projects latency p95 > 2s for 15min”. • “CRITICAL if external X failures > 10 in 10min”. • “INFO (perhaps trending) if usage below threshold (maybe for business KPI). • By planning these, after launch, we can quickly get notified if something goes wrong rather than waiting for user reports.

Let’s finalize in a nicely structured answer including all sections properly.