vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/services/suggestions/prompts/categories/preparation.md

@@ -0,0 +1,37 @@
+# Preparation
+
+## Description
+A preparation suggestion creates readiness for an anticipated event, transition, or demand. It joins present work to a credible trigger and to the response that trigger will require, which means both halves have to be named. The trigger supplies the deadline and the justification; the response supplies the specification of what readiness actually means here. Preparation can take the form of information, decisions, relationships, materials, access, or practice, and the right form follows from what the response will need under time pressure. The work must complete before the trigger arrives, and it must not depend on assumptions that will have decayed by then. Readiness built on a stale assumption is worse than no preparation, because it will be trusted.
+
+The suggestion should define an observable readiness signal that can be checked close to the event, since readiness believed is not readiness demonstrated. It should identify the latest safe completion point, which is usually earlier than the trigger and is the number people misjudge. It should say which readiness assumptions are most likely to decay, and what would refresh them. It should keep any contingency proportionate to the likely disruption, because contingency planning has no natural stopping point and will expand to consume whatever attention it is given. It should say when preparation stops, so that a bounded investment does not become open-ended rehearsal. Where the trigger is too speculative to date or too diffuse to describe, the honest conclusion is that there is nothing specific to prepare for.
+
+## Why use
+Use this category when something is coming that will not leave room to improvise. The defining feature is a compressed response window: at the moment of the event, the time available is less than the time required, so the difference has to be paid in advance. That structure is common and routinely under-appreciated, because the event feels distant right up until it is not, and the cost of the surprise lands on whoever is present rather than on whoever deferred the preparation.
+
+The category also does a second, quieter job. Preparing forces a rehearsal of the response, and rehearsal exposes gaps that planning does not: the access nobody has, the person who was never told, the step that assumes something already dismantled. Much of the value here comes from the discovery rather than from the readiness, which is why the suggestion should favour preparation that actually tests the response over preparation that merely accumulates materials for it.
+
+Distinguish it from the categories nearest to it. Prerequisite concerns a condition that blocks work happening now, whereas preparation concerns readiness for work that will happen later; conflating them makes present blockage look like prudent foresight. Long-term directions concerns a horizon with no specific trigger, and the presence of a datable event is exactly what separates the two. Risk prevention guards against a plausible failure whether or not a scheduled event causes it, and preparation is the right category when the event is expected rather than feared. Continuation advances work already underway. Use preparation when a bounded investment now measurably reduces an expensive surprise later.
+
+## Use cases
+- **A known event has a hard response deadline.** A launch, meeting, migration, audit, or seasonal peak may leave no room to improvise. Build and check readiness before the trigger.
+- **A transition will change responsibilities or conditions.** New ownership, tooling, staffing, or policy may create predictable needs. Use it when the affected people and the required readiness can be identified.
+- **A likely demand could exceed capacity.** Materials, access, training, or fallbacks may be needed before volume arrives. Use it when the demand signal is credible and the preparation is proportionate.
+- **A decision must be made before the event.** Waiting for the trigger may remove the safe or affordable options. Decide early when doing so preserves choice without overcommitting.
+- **A relationship needs lead time.** Stakeholders, partners, reviewers, or suppliers may need notice to participate. Use it when the outreach has a concrete purpose and a date.
+- **Practice would reduce response error.** A rehearsal, simulation, or runbook may expose gaps before the real situation does. Use it when the exercise tests the actual response against a readiness threshold.
+- **Inputs take time to secure.** Access, inventory, data, equipment, or permissions may be unobtainable at short notice. Secure them now when that removes a known failure mode.
+- **A fallback would protect the main response.** A sound plan may still be vulnerable to one predictable disruption. Recommend a proportionate contingency with a clear trigger and activation boundary.
+- **The response depends on someone who may be unavailable.** A single person may hold knowledge, access, or authority needed at the moment of the event. Spread it before the event rather than during it.
+- **Recovery has never been exercised.** A backup, rollback, or failover may exist on paper and never have been run. Test it while failure is optional.
+- **The event will consume attention that planning needs.** Decisions made under the pressure of the event are worse than the same decisions made beforehand. Move them earlier deliberately.
+- **A seasonal or cyclical pattern is approaching again.** A recurring event may have produced known problems last time. Address the specific ones rather than preparing in general.
+
+## When not to use
+- **Work cannot proceed now for want of a condition.** Present blockage is a dependency, not future readiness.
+- **The trigger is too speculative to date.** Preparing for an unspecified event has no deadline and no stopping point.
+- **No readiness signal can be defined.** Readiness that cannot be checked will be assumed.
+- **The work is already underway and needs its next step.** Momentum does not require rehearsal.
+- **The concern is a broad future horizon.** Without a specific trigger, the argument is about direction.
+- **The contingency exceeds the disruption.** Protection more expensive than the failure is a loss taken deliberately.
+
+Route the suggestion elsewhere when one of those signals holds. A blocking condition belongs to prerequisite, and an advancing plan belongs to continuation. A horizon without a trigger belongs to long-term directions, and a plausible failure needing a proportionate guard belongs to risk prevention. If the event's likelihood or shape is genuinely unknown, use investigation before preparing, and if several possible preparations compete for the same capacity, use prioritization.

vidbyte_cli/services/suggestions/prompts/categories/prerequisite.md

@@ -0,0 +1,37 @@
+# Prerequisite
+
+## Description
+A prerequisite is a condition that intended work cannot safely or effectively proceed without. The condition may be evidence, access, capability, authority, preparation, or a prior result, and what unites those forms is that the work stops until the condition exists. The suggestion's job is to make a dependency explicit that has so far been an unexamined source of delay. Its usefulness rests on naming the specific work that becomes possible once the condition is met, because a requirement with no unlocked work behind it is not a requirement anyone needs to act on. The category demands a hard distinction between a true requirement and a strong preference, since those are treated identically by whoever is blocked and are not the same thing at all. Drawing that line is frequently the whole of the contribution.
+
+The suggestion should name who can provide, approve, or create the condition, since an unowned dependency stays unmet however clearly it is described. It should state the observable evidence that the condition exists and remains valid, because conditions expire quietly — credentials lapse, approvals go stale, agreed facts change. It should identify the cheapest safe way to obtain the condition rather than the most complete one. It should ask whether a narrower route or a reduced scope could proceed without it, because a great deal of blocked work is blocked by an ideal setup rather than a genuine gate. It should say what happens if the condition is still unavailable at the decision point, so the blockage has an ending. A prerequisite without an escalation path becomes a permanent excuse.
+
+## Why use
+Use this category when work is not moving and the reason is a condition nobody has named. This is different from a hard problem and different from competing priorities, and it is often invisible to the people closest to the work, who experience it as things being slow. Naming the condition converts an ambient delay into a specific, ownable, obtainable item. That conversion is cheap and is frequently the difference between a week of drift and an afternoon of unblocking.
+
+The category earns its place equally often by making the opposite move. Callers block themselves on conditions that are preferences: a cleaner environment, a complete dataset, a decision that could be made later, an approval nobody actually requires. Testing the condition against what the work genuinely needs releases work that was never truly blocked. That is why the suggestion must ask whether a reduced scope could proceed — the answer is yes more often than the person inside the situation expects.
+
+Distinguish it from its neighbours. Preparation builds readiness for a future event, where a prerequisite blocks work that is wanted now; the tense is the difference. Bottleneck describes a point that limits flow through a system over time, whereas a prerequisite is a specific condition for a specific piece of work. Coordination aligns parties around an interface, and while an agreement can be a prerequisite, the category applies whether or not other parties are involved. Learning builds a capability over time, and prerequisite is the right framing when the capability is needed now and must come from elsewhere. Use prerequisite when one nameable condition stands between the caller and work they are otherwise ready to do.
+
+## Use cases
+- **The next task lacks access or authority.** Work may be ready in every other respect and unable to start legally, technically, or organizationally. Identify the exact approval, credential, or permission.
+- **A decision needs a missing fact or result.** Proceeding without it may invalidate everything built on top. Use it when obtaining the input is necessary rather than merely useful.
+- **A capability must exist before execution.** A skill, tool, capacity, or process may be required for safe completion. Use it when the gap blocks a defined piece of work.
+- **Setup is required for safe progress.** A backup, test environment, or advance communication may be a condition of proceeding. Recommend it when the risk attaches directly to the intended action.
+- **A dependency is hidden in the plan.** The work may look sequentially ready while one external condition stays unstated. Expose the dependency and name its owner.
+- **A preference is masquerading as a requirement.** An ideal setup may be delaying useful action. Test the condition, and say what could proceed without it.
+- **An earlier result gates a later phase.** A measurement, review, prototype, or agreement may determine whether the next phase should begin. Use it when the gate is explicit and meaningful.
+- **The condition has more than one route.** A missing condition may be obtainable several ways or bypassed at reduced scope. Compare the routes rather than accepting the blockage.
+- **A licence, contract, or compliance step is outstanding.** Formal conditions often sit unnoticed until they stop a release. Surface them early, with the owner and the lead time.
+- **A shared environment or dataset is unavailable.** Work may be waiting on something that has to be built, restored, or granted. Name what it is and who supplies it.
+- **An upstream deliverable has not arrived.** Another party may owe an artifact the work depends on. State what is owed, by whom, and by when.
+- **The condition has expired without anyone noticing.** An approval, key, or agreement may have lapsed while the work proceeded. Check validity rather than existence.
+
+## When not to use
+- **The information is interesting but not blocking.** A curiosity does not become a requirement by being relevant.
+- **The condition already exists.** Re-obtaining what is available wastes the unblocking effort.
+- **The real issue is a queue, an owner, or a decision.** Those are different failures with different repairs.
+- **Readiness is for a future event.** A condition for later work is preparation, not a present gate.
+- **The claim that it is required has not been tested.** Unexamined requirements are how work blocks itself.
+- **No one can supply it and no alternative was considered.** A dependency with no route is an abandonment dressed as a plan.
+
+Route the suggestion elsewhere when one of those signals holds. Future readiness belongs to preparation, and a limiting point in the flow belongs to bottleneck. A missing owner or misaligned interface belongs to coordination, and competing claims on capacity belong to prioritization. A claim to be checked belongs to verification, and a fact to be found belongs to investigation. If the capability gap is durable and the caller will need it repeatedly, use learning, and if no route to the condition exists at all, use alternative or stop or defer.

vidbyte_cli/services/suggestions/prompts/categories/prioritization.md

@@ -0,0 +1,37 @@
+# Prioritization
+
+## Description
+A prioritization suggestion helps the caller choose among competing goals, tasks, or commitments that draw on the same scarce resource. Its defining obligation is to make the trade explicit, including what will receive less attention as a direct result of the choice. A ranking that does not name what falls below the line is not a prioritization; it is a wish list in order. The choice should weigh consequence, urgency, reversibility, and the cost of delay together, because urgency alone systematically favours whatever is loudest rather than whatever matters. It should reflect the caller's stated outcomes and constraints rather than the distribution of pressure around them. The output is useful only if it survives the next interruption.
+
+The suggestion should identify the scarce resource precisely, since time, decision bandwidth, capital, and a specific person's attention are different constraints that produce different orderings. It should name what expires: opportunities that close, options that become irreversible, and work whose value decays with delay. It should account for dependency, because sequence sometimes matters more than value when one item unblocks several others. It should name the work, quality, or relationship being displaced, so that the cost of the choice is visible at the moment it is made rather than discovered later. It should propose the smallest commitment that makes the chosen priority operational, because a priority with no first action is a stated intention. It should also give the evidence, date, or event that should trigger reprioritization, since a priority correct today is not permanent.
+
+## Why use
+Use this category when the caller has no shortage of good options and cannot pursue them all. This is a specific failure mode with a specific cost: partial progress on everything, which in most systems delivers less value than complete progress on one thing, and which feels like diligence throughout. Naming the trade is what breaks it, and naming it is uncomfortable, which is precisely why it usually goes unsaid and why a suggestion that says it plainly is worth making.
+
+The category also counteracts a reliable distortion. Attention flows towards recency, visibility, and social pressure rather than towards consequence, and it does so without anyone deciding that it should. Applying explicit values — what expires, what is irreversible, what blocks others, what the caller actually said they wanted — produces a different order from the one the environment generates by default. The gap between those two orders is the value of the suggestion.
+
+Distinguish it from its neighbours. Strategy chooses a direction that coordinates many actions, which changes the criteria rather than applying them to a fixed list. Stop or defer concludes that specific work should leave the list entirely, which prioritization assumes it does not. Goal clarification supplies the outcome that prioritization ranks against, so unclear goals must be settled first or the ranking will be arbitrary. Bottleneck explains why progress is slow for structural reasons rather than because of how attention is allocated. Use prioritization when several worthwhile commitments compete, the outcome is clear, and allocation is the decision to be made.
+
+## Use cases
+- **Several valid tasks compete for the same attention.** Partial progress on all of them may deliver less than completing one. Allocate the scarce time, capacity, or decision bandwidth explicitly.
+- **Delay costs differ sharply.** Some items lose value, create risk, or block others faster than the rest. Compare those costs when doing so changes the order.
+- **The loudest request is not the most important.** Visibility, recency, or pressure may be distorting allocation. Apply stated values and consequences instead.
+- **An irreversible option needs protecting.** A decision or opportunity may expire while reversible work waits safely. Let preservation govern near-term attention.
+- **Focused capacity must go to one constraint.** Several improvements may compete to relieve the same limiter. Choose the highest-impact intervention rather than generating more of them.
+- **Displaced work needs naming.** A new commitment may be accepted without acknowledging what it pushes out. Make the trade explicit to prevent overload and hidden failure.
+- **A deadline is approaching with incomplete scope.** Scope, quality, and timing may need to be traded consciously. Choose the smallest valuable commitment under the constraint.
+- **The order should be provisional.** Today's priority may be right and temporary. Name the review trigger that would change it.
+- **Everything has been marked important.** Uniform priority is the absence of prioritization. Force a ranking, and say what the bottom of it means.
+- **One person is the constraint across several items.** The scarce resource may be a specific individual rather than time in general. Order against that person's availability, not the team's.
+- **Sequence matters more than value.** One lower-value item may unblock several higher-value ones. Order by dependency when the graph dominates the scores.
+- **New work keeps arriving mid-commitment.** Continuous intake may be quietly displacing whatever was agreed. Establish what interrupts and what waits.
+
+## When not to use
+- **Only one meaningful commitment exists.** A ranking of one is not a decision.
+- **An accepted plan already determines the step.** Re-ranking settled work reopens it for no gain.
+- **The outcome is unclear.** Ranking against an undefined goal produces a confident arbitrary order.
+- **The competition comes from a missing owner or condition.** Apparent contention sometimes dissolves once the real blocker is named.
+- **The work should be abandoned rather than ranked.** Keeping dead work on a list keeps it in mind.
+- **A broader direction has to be chosen.** Criteria that do not exist yet cannot be applied.
+
+Route the suggestion elsewhere when one of those signals holds. An undefined outcome belongs to goal clarification, and a direction that sets the criteria belongs to strategy. Work that should leave the list belongs to stop or defer, and a missing condition or owner belongs to prerequisite or coordination. A structural limit on progress belongs to bottleneck, and an accepted plan's next move belongs to continuation. If the caller has capacity but cannot start anything, use immediate next steps rather than another ranking.

vidbyte_cli/services/suggestions/prompts/categories/product_experience.md

@@ -0,0 +1,37 @@
+# Product and Experience
+
+## Description
+A product-and-experience suggestion improves what people can use and how using it feels or works. It starts from a user, a moment, and a friction or desired outcome, never from a feature label, because a feature name describes what would be built rather than what would change for anyone. Naming the person and the moment is what makes the suggestion evaluable, since the same change is an improvement in one context and a burden in another. The proposal has to balance usefulness, clarity, accessibility, trust, and the cost of the complexity it adds, as every addition is paid for by everyone who did not need it. A strong suggestion says how people would recognize the change as better in behaviour or outcome rather than in opinion. Where that recognition cannot be described, there is no way to tell afterwards whether the change helped.
+
+The suggestion should say what evidence supports the friction rather than assuming it, because designers and builders are unreliable witnesses to their own products. It should name which steps, language, defaults, or feedback create the current burden, since the burden is usually specific and the instinct is to redesign broadly. It should address accessibility, privacy, trust, and recovery needs explicitly, as these are the dimensions most often discovered late and most expensive to retrofit. It should say who gains, who loses, and who stays unserved, because experience changes redistribute effort rather than only removing it. It should propose the smallest representative interaction that could test the improvement before broader scope is committed. A prototype that exposes the actual moment answers more than a complete build of the wrong thing.
+
+## Why use
+Use this category when the gap between what a system can do and what people can actually get from it is where the value is being lost. That gap is large in most products and is systematically underestimated, because the people building the system experience none of it. Capability is visible internally and experience is not, so improvements accrue to the former until someone deliberately argues for the latter. This category is that argument, and it has to be made in terms of a specific person at a specific moment or it will lose to any concrete feature request.
+
+The category also disciplines a kind of proposal that is otherwise unfalsifiable. Making something better, cleaner, simpler, or more intuitive cannot be evaluated, accepted, or rejected, and suggestions in that form absorb effort without accumulating knowledge. Requiring an observable behaviour change converts the proposal into something testable, which in turn allows a small prototype to settle a question that would otherwise be decided by whoever argues most persistently.
+
+Distinguish it from the categories nearest to it. Business and growth argues from a commercial mechanism such as acquisition or retention, and while experience changes often drive those, the argument here is from the interaction itself. Technical possibilities concerns what the technology could make better or newly feasible, which is a capability claim rather than a use claim. Simplification removes complexity wherever it has accumulated, including in places no user ever touches. Feedback obtains a reaction and is the right prior step when the friction is suspected rather than evidenced. Use product and experience when a nameable person, at a nameable moment, would behave differently because of the change.
+
+## Use cases
+- **Users struggle at a specific moment.** A task, decision, or transition may contain friction that prevents people from reaching value. Use it when the moment and the affected users can be observed.
+- **A capability exists but its value is invisible.** People may not discover, understand, or trust what is already available. Improve the interaction when that would change real use.
+- **The flow creates avoidable effort.** Extra steps, confusing language, or poor defaults may obstruct a meaningful outcome. Reduce them without removing necessary safeguards.
+- **An accessibility gap excludes people.** Different abilities, devices, languages, or contexts may be unsupported. Specify the affected experience and the inclusive improvement.
+- **A new capability lacks a usable entry point.** Technical availability does not produce adoption. Connect the capability to a real journey rather than to a settings page.
+- **Trust or comprehension is limiting adoption.** People may hesitate because the system is opaque, surprising, or hard to recover from. Improve the interaction that produces the hesitation.
+- **A small prototype would settle an experience question.** A complete build may not be needed to learn what works. Use a representative interaction that exposes the behaviour in question.
+- **Different users face competing trades.** A change may help one audience and burden another. Evaluate it across the affected groups rather than for the loudest one.
+- **Error states are worse than the happy path.** Failure, recovery, and edge conditions are often unattended and are where trust is actually decided. Design the recovery as deliberately as the success.
+- **First use and repeat use need different things.** A design tuned for newcomers may obstruct regulars, or the reverse. Name which population the change serves, and what it costs the other.
+- **A workaround has become common.** Users routinely improvising around the product is precise evidence of an unmet need. Design for the behaviour they already demonstrate.
+- **Support requests cluster on one interaction.** Repeated questions about the same moment are a design signal, not a documentation gap. Fix the moment rather than explaining it better.
+
+## When not to use
+- **No user or system outcome is identified.** A technical capability with no one on the other end is not an experience change.
+- **The argument is commercial.** A growth mechanism with no interaction change belongs with the mechanism.
+- **The goal is unclear.** Improving an experience towards an undefined outcome optimizes taste.
+- **The friction is assumed rather than evidenced.** Redesigning around a guess produces a differently wrong product.
+- **A required completion step is what is missing.** Unfinished work is not an experience problem.
+- **The question is implementation feasibility.** What can be built is a different claim from what people need.
+
+Route the suggestion elsewhere when one of those signals holds. A commercial mechanism belongs to business and growth, and a feasibility question belongs to technical possibilities. An unfinished obligation belongs to completion, and an undefined outcome belongs to goal clarification. Suspected but unevidenced friction belongs to feedback or investigation, and a change whose effect must be measured belongs to experiment. If the complexity being removed is internal rather than experienced, use simplification.

vidbyte_cli/services/suggestions/prompts/categories/quick_wins.md

@@ -0,0 +1,37 @@
+# Quick Wins
+
+## Description
+A quick-win suggestion offers a small, inexpensive action with a useful near-term payoff. It is allowed to sit outside the main plan, which is what distinguishes it from continuation, provided its value is clear and its distraction cost is genuinely low. The payoff must be concrete — time saved, friction removed, evidence created, a loop closed — rather than merely pleasant or easy to count. The action must not depend on a chain of uncertain follow-up work, because a small first step towards an uncertain project is not a quick win but the cheapest part of a large commitment. Cheapness alone is never the argument, since an action can be easy and worth nothing. What justifies the category is a real benefit that arrives soon, at a cost small enough that it does not compete with anything important.
+
+The suggestion should state the specific near-term payoff and the observation by which it will be recognized, because unverified small improvements accumulate into unverified small clutter. It should account for the time, attention, money, and coordination the action requires, and coordination is the one most often omitted and most often decisive. It should say what higher-priority work could be displaced, since the danger of this category is not any single suggestion but the aggregate. It should confirm that the dependencies and follow-up steps really are absent rather than merely unexamined. It should say how soon the payoff appears, and it should give a stopping point if the benefit does not materialize. An action whose benefit cannot be observed within a short horizon belongs to a different category.
+
+## Why use
+Use this category when there is a genuine asymmetry between cost and benefit at small scale. Most work is not like this; most work costs roughly what it returns. The exceptions are worth surfacing precisely because they are exceptions, and because they are usually invisible to whoever is inside the main effort, who has correctly learned to protect their attention from anything not on the plan. A suggestion agent can see the cheap high-return action that the person cannot afford to go looking for.
+
+The category also has a legitimate role after a stall. Work that has been paused for a long time accumulates an activation cost that grows with the pause, and a small completed action can reduce it in a way that further planning cannot. That argument is real, and it is also the argument most easily abused, so the suggestion must require that the completed action produces progress or evidence rather than only relief. A quick win whose entire benefit is feeling better is not one.
+
+Keep the boundary against its neighbours sharp, because this category attracts misuse. If the action is required for the main goal, it belongs to continuation, completion, or prerequisite regardless of how small it is; labelling required work a quick win understates its importance. Adjacent opportunity argues from a closing window on optional value, which is a timing claim rather than a cost-benefit one. Simplification removes accumulated complexity, which may be large. Leverage builds something reused many times, where a quick win pays off once. Use quick wins when the action is small, optional, soon-rewarding, and not the start of something larger.
+
+## Use cases
+- **A small fix removes recurring friction.** Time or clarity may be lost to a simple repeated annoyance. Use it when the fix has a direct payoff and needs no broad redesign.
+- **A cheap action creates immediate evidence.** A measurement, draft, request, or small comparison may clarify a larger choice. Suggest it when the evidence is useful even if nothing follows.
+- **A better default would improve consistency.** A reminder, template, setting, or written-down choice may prevent repeated small errors. Use it when the default is safe and easy to reverse.
+- **Momentum matters after a stall.** A modest completed action can make stalled work concrete again. Recommend it only when completion produces progress rather than relief.
+- **A near-term benefit funds later work.** A small improvement may save time, reduce cost, or demonstrate demand. Use it when the payoff appears within a short horizon.
+- **An action is unusually cheap right now.** Existing access, context, or setup may reduce the cost temporarily. Use it only while the action stays genuinely bounded.
+- **A reversible cleanup improves the current state.** Removing stale clutter, fixing a label, or closing a minor loop may reduce future confusion. Use it when a specific workflow or user benefits.
+- **A minimal exposure would test willingness or usability.** A small trial may teach enough before further investment. Recommend it when the signal is meaningful and the stopping point explicit.
+- **A five-minute task has been deferred repeatedly.** Work that costs more to keep tracking than to finish is pure overhead. Close it, and stop carrying it.
+- **A known annoyance affects several people daily.** A small shared irritation multiplied across a team is not small. Fix it when the aggregate is measurable.
+- **A missing piece of documentation is answering itself repeatedly.** The same question asked weekly has a cheap permanent answer. Write it once, where people already look.
+- **An automatable manual step is short but frequent.** High frequency turns a trivial cost into a real one. Automate it when the automation is itself trivial.
+
+## When not to use
+- **The action is required for the main goal.** Necessary work mislabelled as optional gets deprioritized against its importance.
+- **The only virtue is that it is easy.** Cheapness without payoff is activity.
+- **Follow-up work is large and uncertain.** A small first step into a big commitment is not a small commitment.
+- **The payoff cannot be observed soon.** A benefit with no near horizon cannot be checked and will be assumed.
+- **Attention is already scarce and contested.** Adding optional work to an overloaded queue makes the queue worse.
+- **The upside is large with meaningful exposure.** A consequential opportunity deserves to be argued at its real size.
+
+Route the suggestion elsewhere when one of those signals holds. Required work belongs to continuation, completion, or prerequisite, and contested attention belongs to prioritization. A large, uncertain, high-upside commitment belongs to big bets, and optional value with a closing window belongs to adjacent opportunity. Removing accumulated complexity belongs to simplification, and building something reused repeatedly belongs to leverage. If the small action is really a bounded test of an open question, use experiment so its result gets a decision rule.

vidbyte_cli/services/suggestions/prompts/categories/reframing.md

@@ -0,0 +1,37 @@
+# Reframing
+
+## Description
+A reframing suggestion offers a different interpretation of the problem, one that would change what the caller does next. It works by locating an assumption underneath the repeated symptoms — about cause, ownership, value, or constraint — and proposing that the assumption is what is failing. The new frame must stay tethered to the evidence supplied, because a frame that explains everything and predicts nothing is a slogan. Its value is measured by the actions, boundaries, or trades it changes, which is a concrete test: if the same things get done afterwards, nothing was reframed. The frame should be offered as a lens to test rather than asserted as established fact. A reframe that overclaims is harder to abandon than the interpretation it replaced.
+
+The suggestion should name exactly what is being reinterpreted — a symptom, a boundary, a definition, an assumed cause — so the change is inspectable rather than atmospheric. It should say what evidence makes the alternative plausible and what part of the existing interpretation still holds, because most reframes are partial and pretending otherwise discards knowledge. It should show that the new account explains more than the current one without explaining more than the evidence supports. It should name the observation that would support or undermine the lens, and the small question or check that could distinguish the two frames. It should also say what decision follows if the reframe turns out to be useful but unproven, since that is the common case and the one where guidance is most needed. A reframe offered without that instruction leaves the caller holding two interpretations and no way to act on either.
+
+## Why use
+Use this category when the pattern is repeated failure of reasonable responses. When competent effort keeps not working, the most likely explanation is that the problem being solved is not the problem that exists, and no amount of additional effort on the stated problem will reveal that. Only a change of interpretation will. This is the specific situation where reframing outperforms every other category, and it is recognizable: the fixes are sound, they are applied, and the symptom returns.
+
+The category is also the cheapest intervention available when it works. It costs a conversation and can redirect months of effort, which is a return profile nothing else in the set matches. That asymmetry is exactly why it must be disciplined: the same properties make reframing attractive as a rhetorical move regardless of merit, and an undisciplined reframe substitutes a fresh vocabulary for progress. Requiring a changed action and a discriminating check is what separates the two.
+
+Distinguish it from its neighbours. Creative exploration generates many options inside the existing frame, which is the right move when the frame is fine and the option set is thin. Cross-domain imports a specific tested mechanism from elsewhere, which is a transfer rather than a reinterpretation. Goal clarification sharpens an outcome that is merely vague, whereas reframing replaces an interpretation that is actively misleading. Alternative changes the route while keeping the outcome fixed, and a reframe usually changes what counts as the outcome. Use reframing when changing the question promises more than repeating the answer.
+
+## Use cases
+- **The same symptom keeps returning.** Repeated fixes may be failing because the problem or boundary is misidentified. Offer an interpretation that explains the recurrence and changes the intervention.
+- **The problem is framed around activity rather than value.** Effort may be measured while the intended outcome goes untouched. Shift attention to the beneficiary or result when that alters the next move.
+- **Ownership sits in the wrong place.** A team may be trying to control what it cannot influence, or ignoring a lever it holds. Redraw the boundary when it clarifies responsibility.
+- **A constraint is treated as a fact.** A fixed audience, sequence, resource, or quality bar may be a choice nobody revisited. Challenge it when doing so opens a credible option.
+- **Current labels hide a useful distinction.** One broad problem may contain different needs, failure modes, or horizons. Sharpen the frame when the distinction changes prioritization or evidence.
+- **A conflict may be a measurement mismatch.** Parties can appear opposed because they optimize different definitions of success. Reframe when a shared outcome or explicit trade makes the disagreement actionable.
+- **A failure may be information rather than error.** The result may have exposed a weak premise instead of poor execution. Reinterpret it when that changes what should be tested next.
+- **A different question would enable a better test.** The caller may need to test a different causal claim before continuing. Use it when the new frame yields a discriminating, bounded check.
+- **The unit of analysis is wrong.** A problem framed per-user may be per-session, or per-team may be per-system. Change the unit when the pattern only appears at another one.
+- **Two problems are being treated as one.** A single label may be covering unrelated causes with different remedies. Split it when the split changes what each half needs.
+- **The timescale is misjudged.** A situation read as an incident may be a trend, or the reverse. Reframe when the correct timescale changes the response entirely.
+- **Success is defined by the absence of complaint.** A frame built on silence may be measuring tolerance rather than value. Reinterpret when a positive definition would change the work.
+
+## When not to use
+- **The problem is well-defined and needs execution.** Reinterpreting a clear problem delays it.
+- **The reframe changes no action.** A new vocabulary over the same behaviour is cost without benefit.
+- **It only renames the problem.** Substituting words is not substituting understanding.
+- **The evidence does not support it.** An unfalsifiable frame is harder to escape than the one it replaced.
+- **Many novel possibilities are what is needed.** Widening options inside a working frame is a different move.
+- **The mechanism comes from another field with evidence.** A tested transfer deserves its own discipline.
+
+Route the suggestion elsewhere when one of those signals holds. Execution belongs to continuation, and evidence gathering belongs to investigation. Widening the option space belongs to creative exploration, and importing a tested mechanism belongs to cross-domain. A merely vague outcome belongs to goal clarification, and a different route to a fixed outcome belongs to alternative. If the reframe is plausible and unproven, pair it with experiment so the two interpretations can be separated rather than debated.

vidbyte_cli/services/suggestions/prompts/categories/risk_prevention.md

@@ -0,0 +1,37 @@
+# Risk Prevention
+
+## Description
+A risk-prevention suggestion reduces the likelihood or the impact of a plausible failure. It joins a recognizable exposure to a guard, a signal, or a recovery plan that is proportionate to what the failure would cost. Proportionality is the whole discipline here, because every control has an ongoing burden and a set of controls assembled without regard to cost becomes its own failure mode. The suggestion should address risks capable of changing the outcome rather than every concern that can be imagined, and the difference between those two sets is large. Prevention is strongest when the protection is in place before the exposure begins, since a guard added afterwards protects only the remainder. Where prevention cannot be complete or would cost too much, detection and recovery are the honest substitutes.
+
+The suggestion should describe the failure mode concretely enough to be argued with — how it happens, what it damages, how visible it would be, how reversible. It should identify the prevention point that occurs before the exposure or the commitment, because that point is usually earlier than instinct suggests and is frequently already past. It should say how the control avoids creating a burden equal to or greater than the risk, which is the most common way well-intentioned safeguards are quietly abandoned. It should name the signal that would detect the failure early enough to matter, since detection after compounding is not detection. It should name the fallback that preserves the core obligation when the primary route fails. It should also name who owns the control, monitors it, and revises it when conditions change, because an unowned control decays into a false assurance.
+
+## Why use
+Use this category when a specific failure is plausible, consequential, and cheaper to guard against than to repair. That combination is narrower than general caution and much more useful. Most concerns fail one of the three tests: they are imaginable but not plausible, plausible but not consequential, or consequential but no cheaper to prevent than to fix. Filtering on all three is what makes a prevention suggestion worth the reader's attention rather than another item on a list of things that could go wrong.
+
+The category also addresses a timing asymmetry that people reliably misjudge. The cost of a guard falls over time until the moment of exposure, after which it rises sharply, and the window in which prevention is cheap closes quietly and without announcement. A suggestion that names the last cheap moment is doing something the caller almost certainly is not doing for themselves, because attention at that stage is fully occupied by making the thing work.
+
+Distinguish it from the categories around it. Verification confirms that a specific claim is true before something is relied on, which is a check rather than a guard, though a verification can serve as one. Preparation builds readiness for an expected event, where prevention addresses a failure that may never occur. Bottleneck relieves a constraint on flow rather than protecting against a failure. Stop or defer removes the exposure entirely by not doing the thing, which is sometimes the correct and unwelcome answer. Use risk prevention when the work should continue and one proportionate control materially improves its odds.
+
+## Use cases
+- **A known failure mode could derail the outcome.** There may be enough context to describe exactly how the failure would occur. Add a guard that reduces likelihood or impact before exposure grows.
+- **An irreversible action is approaching.** A check, backup, approval, or staged release may preserve recovery before the point of no return. Keep the protection proportionate to the consequence.
+- **A handoff can lose critical information.** Ambiguous ownership, missing context, or an unverified interface may produce predictable failure. Add a narrow contract or confirmation at the boundary.
+- **A small control prevents expensive rework.** A validation, limit, default, or precondition may catch the problem early. Recommend it when the control costs less than repairing the result.
+- **Exposure is growing faster than confidence.** The work may be reaching more users, systems, data, or stakeholders than the evidence supports. Add staged exposure or a leading signal.
+- **Detection is slower than the consequence.** An alert, audit, or checkpoint may be needed before the failure compounds. Use it when faster detection creates a credible recovery window.
+- **A fallback would preserve the core obligation.** The primary route may fail despite reasonable safeguards. Define a concrete alternate path or recovery state.
+- **A recurring incident needs a durable guard.** Repeated warnings or manual fixes suggest prevention belongs in the workflow. Recommend it when the pattern and the control's owner are both clear.
+- **A single point of failure has no cover.** One person, credential, dependency, or machine may hold the whole path. Reduce the concentration, or make the failure survivable.
+- **A quiet failure mode exists.** Some failures produce no signal until damage is substantial. Add observability specifically where silence is possible.
+- **The blast radius is larger than the change.** A small modification may reach far beyond its apparent scope. Contain it before shipping, not after.
+- **Assumptions are being carried into a new context.** Controls designed for one scale, region, or population may not hold in another. Re-examine them at the boundary rather than after the incident.
+
+## When not to use
+- **The concern is hypothetical.** Imaginable failures with no plausibility consume attention indefinitely.
+- **The control burden exceeds the consequence.** Protection more expensive than the loss is a loss chosen deliberately.
+- **No one can own or maintain the control.** An unmaintained guard becomes false assurance, which is worse than none.
+- **The claim simply needs checking.** Confirming a fact is not the same as guarding against a failure.
+- **The goal is unclear.** Protecting an undefined outcome protects nothing in particular.
+- **The right answer is to drop the exposure.** Guarding work that should not happen is an expensive way to keep it.
+
+Route the suggestion elsewhere when one of those signals holds. A claim to confirm belongs to verification, and readiness for an expected event belongs to preparation. A limiting constraint belongs to bottleneck, and removing the exposure belongs to stop or defer. An undefined outcome belongs to goal clarification, and an unknown likelihood belongs to investigation or experiment. If the risk comes from complexity that nobody needs, simplification removes the exposure rather than guarding it.

vidbyte_cli/services/suggestions/prompts/categories/simplification.md

@@ -0,0 +1,37 @@
+# Simplification
+
+## Description
+A simplification removes avoidable scope, components, coordination, or cognitive load while protecting the result that matters. It is a subtractive suggestion, and subtraction has to be specific: what is removed must be named, because praising simplicity in the abstract commits nobody to anything and changes nothing. The central judgment is separating optional machinery from the parts that downstream users, operators, or decisions actually depend on. That separation is not obvious from inside the work, where every piece has a remembered reason and the reasons are no longer all valid. Complexity accumulates one defensible decision at a time, which is why it is rarely removed by the same process that created it. A simplification is the deliberate counter-move.
+
+The suggestion must also state what the reduction costs, since every removal creates a new limitation, risk, or foreclosed option. Claiming a simplification is free is the fastest way to have it reversed by the first person who needed the removed capability. It should name the evidence that the current complexity is producing cost or confusion, rather than asserting that fewer things are better. It should identify who could be harmed by the removal and whether the burden is being genuinely eliminated or merely shifted to another owner, because shifted burden is the most common counterfeit in this category. It should say whether the reduction is reversible without losing important state. It should say how the simpler result will be verified against the original acceptance condition, and which expansion seam remains available without being built now.
+
+## Why use
+Use this category when accumulated complexity has become the thing limiting the work rather than a side effect of it. This happens on a predictable schedule, because complexity is added incrementally by people solving real problems and removed by nobody in particular. The cost shows up diffusely — slower changes, more coordination, more places to be wrong, a longer explanation for every newcomer — and diffuse costs do not generate their own repair. Naming the specific removable piece is what converts a general feeling of heaviness into an action.
+
+The category also earns its place by countering a specific bias in suggestion-making. Almost every other category proposes adding something: a step, a check, an asset, a test, a direction. Over time an advisor that only adds becomes a source of burden regardless of the quality of each individual suggestion. Having a category whose move is removal keeps the total load in view, and it makes it possible to recommend subtraction as a first-class action instead of an apology.
+
+Distinguish it from its neighbours. Stop or defer abandons work entirely, where simplification keeps the outcome and reduces the means. Completion closes a remaining obligation rather than removing an existing one. Leverage often argues in the opposite direction, towards shared machinery, and the two should be weighed against each other rather than applied in sequence. Bottleneck relieves a constraint on flow, which complexity can cause but does not exhaust. Use simplification when the essential result survives intact and the effort or clarity saved exceeds what is given up.
+
+## Use cases
+- **Optional scope has accumulated.** Extra features, formats, audiences, or edge cases may dilute the essential result. Remove a named portion without weakening the commitment that matters.
+- **A workflow has too many steps or handoffs.** Repeated coordination may add delay without adding quality or control. Shorten the path while preserving the necessary decision and acceptance points.
+- **A component costs more than it returns.** A tool, abstraction, integration, or configuration may have become a liability. Remove or replace it with a simpler mechanism.
+- **Users or operators must hold too much context.** Complex choices, labels, or exceptions may produce errors and hesitation. Use a clearer default or a smaller choice set while preserving real control.
+- **Generality arrived before the pattern.** Flexibility may have been built before a stable shape existed. Narrow the solution and leave a deliberate expansion seam.
+- **A requirement has been confused with its implementation.** The current machinery may be one route to the outcome rather than the outcome. Propose a simpler route that meets the same acceptance condition.
+- **Fewer parts would improve reliability.** Reducing moving parts, states, or dependencies may lower failure probability. Use it when the gain is checkable and the removed capability is understood.
+- **The result must be explainable.** Complexity may be preventing adoption or review. Reduce the concepts when that makes the important behaviour inspectable.
+- **Two mechanisms do the same job.** Parallel paths that overlap force everyone to know both. Consolidate, and say which one survives.
+- **Configuration has replaced decisions.** Options may exist because nobody wanted to choose. Pick a default, and remove the choice that nobody exercises.
+- **Dead paths remain in place.** Code, process, or documentation may serve a case that no longer exists. Remove it once the case is confirmed gone.
+- **Onboarding is the symptom.** A long explanation for newcomers is a reliable measure of accumulated complexity. Target what takes longest to explain.
+
+## When not to use
+- **The complexity is a true prerequisite.** Removing a required condition creates a failure, not a simplification.
+- **The removed part is a safety control.** Guards look like overhead precisely when they are working.
+- **A real user need depends on it.** A capability with users is not optional because it is inconvenient.
+- **The reduction hides an unresolved decision.** Deferring a choice by deleting its surface does not resolve it.
+- **The burden is shifted rather than removed.** Moving work to another owner is a transfer wearing a saving's clothes.
+- **The work no longer earns its cost at all.** Making unwanted work simpler still produces unwanted work.
+
+Route the suggestion elsewhere when one of those signals holds. Work that should end belongs to stop or defer, and a required condition belongs to prerequisite. A protective control belongs to risk prevention, and a real user need belongs to product and experience. Competing commitments belong to prioritization, and a shared asset that would remove repeated cost belongs to leverage. If the complexity is the limiter on flow rather than on comprehension, use bottleneck so the intervention targets the constraint.

vidbyte_cli/services/suggestions/prompts/categories/stop_or_defer.md

@@ -0,0 +1,37 @@
+# Stop or Defer
+
+## Description
+A stop-or-defer suggestion protects attention from work whose present value no longer justifies its cost. The two halves are different decisions and should not be blurred. Stopping ends a direction and accepts the loss of the option, which is why it requires a case strong enough to be stated plainly. Deferring preserves the option and names the condition, date, or evidence that would make it worth revisiting, which is only honest if that trigger is real rather than a polite way of never returning. Both require saying what more valuable work receives the released capacity, because a recommendation to stop with nothing on the other side of it is a recommendation to do less. The category exists because continuing is the default and defaults do not get examined.
+
+The suggestion should separate sunk cost from future value explicitly, since prior investment is the most reliable reason low-value work continues and the least valid one. It should name what option value is lost by stopping, because pretending a stop is free makes it easy to reverse and hard to trust. It should say what state, rationale, artifacts, and ownership must be preserved for a responsible restart, as a deferral that destroys its own context is a stop with extra steps. It should identify who needs to know and what ambiguity the announcement must remove, because half-stopped work consumes attention indefinitely while nobody is willing to say it is over. It should name the trigger for reconsideration where one exists, and say clearly when none does. Ambiguity about whether something is stopped is more expensive than either outcome.
+
+## Why use
+Use this category when the honest assessment is that continuing costs more than it returns, and when nothing in the situation will make that judgment for itself. Work does not stop on its own. It accumulates commitment, identity, and sunk cost, all of which argue for continuation independently of value, and the people closest to it are the least able to make the call. A suggestion that says it plainly, with the evidence and the threshold visible, is doing something structurally difficult from the inside.
+
+The category also has a second function that is easy to miss: it makes deferral respectable. Much low-value work continues because the alternatives on offer are to keep going or to admit defeat, and a conditional pause with a named restart trigger is neither. Offering that option releases capacity without forcing anyone to write off the idea, which makes the recommendation far more likely to be acted on. The condition is that the trigger must be specific, or the deferral becomes a euphemism and the work stays half-alive.
+
+Distinguish it from its neighbours. Prioritization ranks commitments that all remain on the list, whereas this category removes one from it. Simplification reduces the means while keeping the outcome, which is the right move when the goal is still worth something. Alternative changes the route to an outcome still worth reaching. Completion closes a remaining obligation, and where the last step is small and required, finishing usually beats abandoning. Use stop or defer when the outcome itself no longer earns its cost, or when the timing makes pursuing it now a mistake.
+
+## Use cases
+- **Expected value has fallen below cost.** New evidence may show the work will not repay its time, money, or attention. Make the reason and the threshold visible.
+- **A higher-value commitment is being crowded out.** Continuing may consume the scarce resource something better needs. Name the displaced work and its clearer consequence.
+- **A dependency will not arrive in time.** Waiting actively may produce repeated context switching and idle effort. Defer when the state can be preserved and a real trigger determines resumption.
+- **The direction no longer fits the goal.** A changed outcome, market, constraint, or owner may have made the work irrelevant. Stop when continuing serves a commitment nobody endorses.
+- **A good idea has the wrong timing.** The idea may be valuable and unaffordable under current conditions. Defer when preserving the option costs less than pursuing it.
+- **More effort will not resolve the core issue.** Repeated attempts may be accumulating cost without producing new evidence. Stop when no credible intervention or learning path remains.
+- **The work continues only because it started.** Existing effort creates pressure to finish regardless of value. Separate the sunk cost from the value of what remains.
+- **A clean pause would reduce harm.** Continuing may increase risk, confusion, or stakeholder burden while conditions are unstable. Defer when the restart state and owner can be maintained.
+- **The original assumption has been disproved.** The premise the work was built on may no longer hold. Stop rather than redirecting effort towards a goal that has dissolved.
+- **Maintenance exceeds use.** An existing asset or process may cost more to keep than anyone gains from it. Retire it deliberately, with notice to whoever remains.
+- **Nobody owns it.** Work with no owner consumes attention diffusely and finishes never. Assign it or end it, rather than leaving it nominally alive.
+- **The same decision keeps being deferred informally.** Repeated quiet postponement is a decision that nobody has taken responsibility for. Make it explicit in one direction or the other.
+
+## When not to use
+- **The work is merely difficult.** Difficulty is not evidence about value.
+- **The block is temporary and the direction sound.** A short wait is not a reason to abandon.
+- **The next step is small and required for completion.** Finishing is usually cheaper than unwinding.
+- **A prerequisite can be obtained promptly.** An obtainable condition is not a dead end.
+- **Competing commitments need ranking.** Deciding what comes first is different from deciding what leaves.
+- **A smaller, safer test would settle it.** Stopping on uncertainty forfeits information that was cheap to get.
+
+Route the suggestion elsewhere when one of those signals holds. Ranking live commitments belongs to prioritization, and a small remaining obligation belongs to completion. An obtainable missing condition belongs to prerequisite, and a safer bounded test belongs to experiment. A different route to an outcome still worth reaching belongs to alternative, and reducing the means while keeping the outcome belongs to simplification. If the value is genuinely unknown rather than low, use investigation before recommending a stop.

vidbyte_cli/services/suggestions/prompts/categories/strategy.md

@@ -0,0 +1,37 @@
+# Strategy
+
+## Description
+A strategy suggestion chooses a broader direction that coordinates several later actions. Its purpose is to make trades, opportunity costs, and boundaries visible before local execution compounds them into a shape nobody chose. A direction must constrain: if it permits every action that was already permitted, it is a description rather than a strategy, and it will guide nothing. At the same time it must not pretend to knowledge it lacks, so it constrains at the level of principle and leaves the details to be discovered. It connects its rationale to the caller's stated outcome, context, and evidence, since a direction detached from those is a preference with authority borrowed from the word. The test is whether two people applying it to the same decision would reach the same answer.
+
+The suggestion should state the non-goals as explicitly as the goals, because what will not be optimized is where a strategy does its work and is the part most commonly omitted. It should compare the alternatives that were rejected and say what each would have cost, so the choice can be examined rather than accepted. It should name the assumptions that connect the direction to the desired outcome, since those are what a changing environment will attack first. It should identify leading signals that show progress before final results arrive, and the evidence that would require revision. It should name a review point, because an unreviewable direction becomes an identity. It should also propose one immediate action that tests whether the strategy is usable in practice, as directions that cannot be applied to a real decision this week usually cannot be applied at all.
+
+## Why use
+Use this category when local decisions keep conflicting because nothing connects them. That pattern is recognizable: each choice is defensible, the aggregate is incoherent, and no individual decision can be identified as the mistake. The missing input is a direction, and adding one resolves not just the current decision but the class of decisions it belongs to. That multiplier is what makes strategy worth the effort it costs, and it is also why strategy applied to a single decision is overhead.
+
+The category also exists to force a trade into the open. Organizations avoid stating what they will not do, because non-goals create losers immediately while goals create winners eventually. The result is a direction that everyone can agree with and nobody can apply, which is worse than no direction because it consumes the occasion for making a real one. Requiring explicit non-goals and rejected alternatives is what keeps this category from producing that.
+
+Distinguish it from its neighbours carefully. Alternative chooses between two concrete routes to one outcome, where strategy sets the criteria by which such choices get made. Big bets asks for a large, concentrated, partly irreversible commitment, which a direction may imply but does not require. Long-term directions concerns capability worth developing over a horizon without demanding present subordination. Prioritization ranks commitments against criteria that already exist, and where the criteria are the problem, ranking harder will not help. Goal clarification defines the outcome the strategy serves and must come first when it is missing. Use strategy when one directional choice would make several later decisions coherent.
+
+## Use cases
+- **Several actions need a shared direction.** Local decisions may conflict because no principle connects them. Choose the direction that makes later sequencing and trades coherent.
+- **Concentration must be decided.** Time, capital, capability, or attention cannot support every plausible route. Set the allocation when it should shape multiple downstream commitments.
+- **A recurring decision needs a governing principle.** Teams may be choosing inconsistently under similar conditions. Define the direction that makes those choices faster and aligned.
+- **The environment has changed materially.** New constraints, opportunities, competitors, users, or technology may have invalidated the old path. Use it when the response must coordinate more than one adjustment.
+- **Several viable paths have different consequences.** The choice may affect reach, quality, speed, resilience, or future options. Compare at the level of direction rather than task by task.
+- **A position must be built deliberately.** Short-term actions may not accumulate into durable advantage without consistency. Use it when sequencing over time is what creates the value.
+- **An explicit trade is needed.** A direction can state what will not be pursued or optimized. Use it when the avoided option matters as much as the chosen one.
+- **The direction should stay conditional.** Evidence may still be accumulating while decisions cannot wait. Name the leading indicators and the review point that keep it accountable.
+- **Two parts of the organization are pulling apart.** Divergence usually reflects an unstated directional choice rather than bad faith. Make the choice, and say which local goal yields.
+- **Repeated escalations land on the same question.** A decision that keeps returning to one person is a missing principle. Convert the judgment into a rule others can apply.
+- **A default is operating unexamined.** An inherited direction may still be shaping decisions long after its rationale expired. Restate or replace it deliberately.
+- **Scope keeps growing because nothing is excluded.** Without non-goals, every reasonable request qualifies. Draw the boundary at the directional level rather than per request.
+
+## When not to use
+- **The next action is already clear.** A direction added on top of a settled action is ceremony.
+- **One narrow check would resolve it.** Strategy is an expensive answer to a factual question.
+- **The direction has no trade.** A statement everyone endorses constrains nobody.
+- **It cannot guide more than one decision.** A direction for a single choice is just that choice.
+- **The outcome itself is undefined.** A direction towards nothing in particular cannot be evaluated.
+- **The commitment is unusually large and uncertain.** Exposure of that size deserves to be named rather than implied.
+
+Route the suggestion elsewhere when one of those signals holds. Two concrete routes to one outcome belong to alternative, and a large uncertain commitment belongs to big bets. A capability worth developing over a horizon belongs to long-term directions, and ranking against existing criteria belongs to prioritization. An undefined outcome belongs to goal clarification, and a factual question belongs to investigation or verification. If the direction is clear and the problem is that nothing is moving, use continuation or immediate next steps.

vidbyte_cli/services/suggestions/prompts/categories/technical_possibilities.md

@@ -0,0 +1,37 @@
+# Technical Possibilities
+
+## Description
+A technical-possibilities suggestion explores what technology could make materially better or newly feasible. It operates at the level of capability and the value that capability creates, not at the level of implementation detail, because prescribing the mechanism before the value is established reverses the order in which those should be decided. The possibility must attach to a real constraint, opportunity, or desired outcome in the caller's situation rather than to the general availability of a technique. What the suggestion has to name is the new behaviour, scale, speed, quality, or reliability that becomes available, and why that change matters to someone. Technical novelty that adds complexity without changing a result or a decision is a cost, and an easy one to incur. The category is for separating a promising capability from an attractive fantasy.
+
+The suggestion should name the feasibility question that is most decision-critical, since a capability usually stands or falls on one thing — latency, data quality, integration, accuracy, control, cost — rather than on the whole design. It should propose the smallest prototype or measurement that would answer that question, because feasibility is cheap to test and expensive to assume. It should name the data, integration, dependency, and operational burden the capability would introduce, as these accumulate quietly and are paid by people who were not in the conversation. It should say who would own and maintain the result, which is the commitment that outlasts the enthusiasm. It should compare the technical route against the non-technical alternatives — process, staffing, scope — because those are frequently cheaper and are rarely considered once a technical framing takes hold. It should say what result would make the simpler route better.
+
+## Why use
+Use this category when a constraint everyone treats as fixed may not be. Teams build durable habits around limits — this takes a day, that cannot be automated, this must be approximate — and those habits persist long after the underlying limit has moved. Surfacing a capability that changes the limit is high-value precisely because nobody inside the habit is looking for it. The suggestion has to carry the value argument, though, since a capability with no constraint behind it is a technology looking for a problem.
+
+The category also protects a specific decision from being made badly. Technical possibilities are usually evaluated either by enthusiasm or by reflexive caution, and both are poor instruments. Naming one decision-critical feasibility question and a small test to answer it replaces both with evidence, and it does so at a cost low enough that the test can be run before anyone has committed to a position. That is the strongest argument this category makes, and it should appear in most suggestions written under it.
+
+Distinguish it from the categories nearest to it. Product and experience argues from a person at a moment and what they would do differently, where this category argues from what becomes possible at all. Experiment tests an uncertainty to inform a decision, and a feasibility spike is a species of experiment, so the distinction is that here the uncertainty is specifically about technical capability. Verification checks whether a claimed capability already works as stated, which is a different question from whether it could. Leverage builds a reusable asset, which a new capability may become but is not by default. Use technical possibilities when the relevant question is what technology makes newly achievable and whether that is worth having.
+
+## Use cases
+- **A current constraint may be technically changeable.** Speed, scale, access, accuracy, or reliability limits may not be permanent. Use it when a capability could move the constraint and the value of moving it is clear.
+- **A new system behaviour would unlock an outcome.** Automation, integration, computation, or sensing may enable what the current process cannot. Argue from the behaviour rather than the technology's name.
+- **A manual process is limiting scale.** Repetition may be consuming capacity or introducing inconsistency. Use it when the capability improves the outcome without relocating the work invisibly.
+- **A platform already exposes the capability.** Existing infrastructure may make a new path unusually cheap. Map it to a specific user, system, or business need.
+- **A technical choice could improve resilience.** Redundancy, observability, isolation, or graceful degradation may reduce real exposure. Tie the benefit to a defined failure or service expectation.
+- **A prototype would settle feasibility cheaply.** The open question may be whether latency, integration, data quality, or control is achievable. Use a small spike when its result changes the broader decision.
+- **A capability could reduce operator burden.** Better interfaces, defaults, or assistance may be technically enabled. Identify the burden and the improved behaviour rather than assuming automation helps.
+- **The technical route should be compared with non-technical ones.** Process, staffing, or scope changes may compete directly. Recommend it when the technical route has a distinct advantage worth testing.
+- **An assumption about cost has aged.** Compute, storage, bandwidth, or model capability may have changed the economics of a rejected idea. Re-examine the decision rather than the technology.
+- **Data that exists is not being used.** A signal may already be collected and never applied. Name what the capability would do with it, and for whom.
+- **A quality ceiling is set by the method, not the effort.** More care may not improve a result that a different technique would improve structurally. Propose the technique and the check that it helps here.
+- **Two systems could be connected.** An integration may remove a manual bridge nobody counts. Use it when the connection's operational burden is stated alongside its saving.
+
+## When not to use
+- **The detail is untied to an outcome.** Implementation preferences without a value claim are not possibilities.
+- **The technology was chosen for novelty.** Interest is not a constraint that needs removing.
+- **The user or system need is unclear.** A capability serving no identified need cannot be evaluated.
+- **The capability is known and merely needs building.** Execution of a settled choice is not exploration.
+- **The concern is how people experience the result.** Experience arguments belong with the experience.
+- **The claim is that it already works.** Whether something performs as stated is a check, not a possibility.
+
+Route the suggestion elsewhere when one of those signals holds. Experience of the result belongs to product and experience, and a claim of current behaviour belongs to verification. A settled capability that needs building belongs to continuation, and a reusable asset with named consumers belongs to leverage. A commercial mechanism belongs to business and growth, and a large, uncertain, concentrated commitment belongs to big bets. If the feasibility question is the whole of the suggestion, use experiment so the spike gets a decision rule.

vidbyte_cli/services/suggestions/prompts/categories/verification.md

@@ -0,0 +1,37 @@
+# Verification
+
+## Description
+A verification suggestion tests a claim that the caller's next decision depends on. The claim may concern a requirement, a piece of evidence, a behaviour, a state of readiness, a safety property, or the result of earlier work. What makes it verification rather than investigation is that the claim already exists and is believed; the question is whether belief matches reality. The check should be narrower than the whole goal while still representing the risk of proceeding, which is the balance the suggestion has to strike. A useful verification states in advance what would count as support, what would count as failure, and what would leave the matter unresolved, because a check without a pass condition returns whatever the checker expected. It must rest on an observable or authoritative source rather than on intent, memory, or the confidence of whoever made the claim.
+
+The suggestion should say why being wrong matters at this point in the work, since the value of a check is proportional to what is about to be built on it. It should identify the specific source, observation, test, or authority that can establish the claim, because "confirm this" without a means is not a check. It should target the edge, boundary, or failure condition that is most consequential, as claims usually fail there and are usually tested in the middle. It should say what decision follows from each possible result, which is also the test of whether the check is worth running. It should name the evidence to retain so that someone else can inspect the status later, because verification that leaves no record has to be repeated. Where the claim is too vague for a pass condition, the claim needs sharpening before it can be checked at all.
+
+## Why use
+Use this category when something believed true is about to be relied on, and the cost of it being false is meaningfully larger than the cost of checking. This is one of the highest-return actions available in most work, and it is systematically skipped, because the claim in question is usually one that a competent person already asserted and re-examining it feels redundant. It is not redundant. Most expensive failures trace back to a true-seeming assumption that nobody tested at the point where testing was still cheap.
+
+The category also does something for honesty that no other category does. It produces a defensible statement of status: not that the work looks right, but that this specific condition was observed, against this source, on this date. That is what allows responsibility to move between people and what stops the same question from being re-argued each time it comes up. The requirement to retain inspectable evidence is what converts a private check into that shared status.
+
+Distinguish it from its neighbours. Investigation answers an open question through inquiry, whereas verification tests a specific claim against a known acceptance condition; the difference is whether the answer is expected. Experiment intervenes to produce evidence about an uncertain effect, so it applies when nobody knows the outcome rather than when someone believes they do. Completion closes a remaining obligation, and verification often serves as its acceptance evidence without being the obligation itself. Risk prevention adds a guard against a failure, where verification establishes whether the failure is already present. Use verification when one focused check makes the status of a consequential claim honest and actionable.
+
+## Use cases
+- **A requirement is claimed satisfied.** The work may look complete while one acceptance condition is unconfirmed. Check it directly before treating the result as done.
+- **A decision rests on an unconfirmed premise.** The choice may be safe only if a particular fact holds. Confirm it against an authoritative source or a direct observation.
+- **Behaviour may differ from design.** What the system actually does under the relevant condition may not match intent. Establish it with a reproducible observation.
+- **Readiness is asserted before exposure.** A release, handoff, launch, or migration may depend on an inspectable state. Check it when the check catches a consequential gap before commitment.
+- **A fix may work only on the happy path.** The claim may need a boundary, failure, or representative case. Test the relevant edge while it is still cheaper than discovering the gap later.
+- **Evidence is being summarized without a source check.** A citation, measurement, or record may not support the conclusion drawn from it. Trace the claim back when doing so could change confidence or action.
+- **Two parties disagree about status.** A shared observation can settle whether the disagreement is factual. Use it when an agreed source exists and no negotiation is required.
+- **A gate or policy must be demonstrated.** Evidence may be needed that a control, permission, or standard is actually satisfied. Use it when the pass condition and evidence record are explicit.
+- **A long-standing assumption has never been tested.** Beliefs inherited from earlier conditions may no longer hold. Check the ones the current plan leans on hardest.
+- **A dependency claims a guarantee.** A vendor, library, or team may assert behaviour that has not been observed here. Verify under the conditions that matter to this use.
+- **A number is being reused out of context.** A measurement taken under different conditions may no longer apply. Confirm it in the setting where it is being relied on.
+- **A migration claims parity.** Old and new paths may be asserted equivalent without comparison. Check the cases where they would most plausibly diverge.
+
+## When not to use
+- **The fact is unknown rather than believed.** Open-ended inquiry is a different instrument from a targeted check.
+- **The effect of a new intervention is uncertain.** Where nobody knows the outcome, something has to be tried.
+- **The claim is too vague for a pass condition.** A check without a threshold confirms whatever was expected.
+- **No result would change the next decision.** A check with no consequence is a ritual.
+- **The obligation simply needs closing.** Finishing work is not the same as testing a claim about it.
+- **A guard is needed rather than a status.** Preventing a failure is a different act from detecting one.
+
+Route the suggestion elsewhere when one of those signals holds. An unknown fact belongs to investigation, and an uncertain effect belongs to experiment. A remaining obligation belongs to completion, and a proportionate guard belongs to risk prevention. A claim too vague to test belongs to goal clarification, and a judgment that only a person can supply belongs to feedback. If the check would pass and the real doubt is whether the work is worth continuing, use stop or defer.