vidbyte-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,37 @@
+# Coordination
+
+## Description
+A coordination suggestion aligns people, ownership, timing, or dependencies so that related work can proceed together. It addresses friction at the interfaces between actors rather than the internal quality of any one actor's task. The distinguishing feature is that no individual is failing and the work is still stuck, because the failure lives in an agreement nobody made. That agreement might concern who owns a boundary, when a dependency arrives, what a handoff must contain, or who has authority to settle a conflict. Coordination problems are easy to mistake for effort problems, since the visible symptom is usually that something did not get done. The correct test is whether the obstacle would survive if every party worked harder in isolation.
+
+The suggestion should name the parties, the shared outcome that connects them, and the exact mismatch between them. It should prefer a decision, an owner, or a handoff contract over more status communication, because reporting the misalignment more often does not resolve it. It should say who is accountable once the coordination action is taken, since an alignment with no owner decays back to its original state. It should define the smallest synchronization point that releases the blocked work rather than the most complete process that could be imagined. It should say how the agreement gets recorded and made visible, because unrecorded agreements are renegotiated silently. It should not create meetings or process unless they resolve a named coordination failure, since ceremony is the most common substitute for an actual decision.
+
+## Why use
+Use this category when the obstacle lives between people rather than inside anyone's work. This is a specific and common failure shape: two competent parties, a shared objective, and a boundary neither of them owns. It resists effort by construction, because the work each party can do alone is already done. Naming the mismatch is what unblocks it, and naming it precisely — ownership, timing, authority, information, or interface — is what determines which repair will work.
+
+The category also exists to resist the default response to misalignment, which is to add communication. More status reporting makes a coordination failure more visible without making it smaller, and it consumes exactly the attention the parties need in order to act. Requiring the suggestion to propose a decision, an owner, or a contract keeps it pointed at resolution. Requiring an accountable party afterwards keeps the resolution from being temporary.
+
+Distinguish it from the categories around it. Bottleneck concerns a point in a system that limits flow, which may be a coordination failure but is argued from throughput rather than from an unmade agreement. Delegation moves a defined piece of work to a better-placed owner, where coordination decides who owns a boundary in the first place. Prerequisite creates a missing condition, and while an agreement can be a prerequisite, coordination is specifically about aligning parties rather than about any missing condition. Strategy chooses a direction that many actions serve, which resolves conflicting local goals by subordinating them rather than by negotiating an interface. Use coordination when two or more parties must act consistently and currently cannot.
+
+## Use cases
+- **Two owners each assume the other will act.** An unassigned boundary can leave a task waiting with nobody seeing it as theirs. Establish one accountable owner and the inputs that owner receives.
+- **A dependency has no agreed timing.** Both sides may be individually ready and badly sequenced. Suggest a date, trigger, or service expectation that lets both sides plan.
+- **A handoff loses information.** Work crossing teams or tools may arrive without context, acceptance criteria, or a responsible party. Define the smallest handoff contract that preserves what the receiver needs.
+- **Groups are optimizing conflicting outcomes.** Local goals can produce delay, duplication, or incompatible decisions. Recommend a shared outcome or an explicit trade that aligns them.
+- **A decision needs the right participants once.** The issue may be blocked because authority, expertise, or affected parties are absent. Arrange one focused decision with a named outcome rather than a standing meeting.
+- **Parallel work risks collision.** Independent actions may touch the same resource, assumption, or interface. Suggest a boundary, lock, sequence, or shared record that prevents interference.
+- **An external party controls the next step.** A supplier, partner, reviewer, or platform may owe something specific. Use it when the request, the owner, and the escalation path can all be made explicit.
+- **A commitment changed without downstream alignment.** New scope, timing, or constraints may have invalidated assumptions others still hold. Recommend notifying and renegotiating the affected boundary.
+- **The same misunderstanding keeps recurring.** Repeated confusion at one interface usually indicates a missing definition rather than careless people. Propose the definition, and say where it lives.
+- **Authority is ambiguous in a dispute.** Two parties may disagree with no agreed way to settle it. Name the decision-maker and the criteria, rather than arguing the case again.
+- **A shared artifact has no owner.** A document, schema, environment, or process may be used by everyone and maintained by no one. Assign maintenance explicitly, with a scope.
+- **Work is being duplicated across groups.** Two efforts may be solving the same problem without either knowing. Suggest the smallest visibility mechanism that would have prevented it, and who runs it.
+
+## When not to use
+- **The obstacle is inside one person's task.** A solitary difficulty does not become coordination because others care about the result.
+- **No dependency between actors exists.** Without an interface there is nothing to align.
+- **The proposal is a status meeting.** Reporting the mismatch is not resolving it.
+- **The suggestion adds process without naming a failure.** Ceremony introduced speculatively becomes overhead that outlives its cause.
+- **One scarce stage is limiting everyone.** That is a property of flow rather than of agreement.
+- **The conflict is really about direction.** Parties pulling different ways because the objective is unsettled need the objective settled.
+
+Route the suggestion elsewhere when one of those signals holds. A limiting stage belongs to bottleneck, and an unsettled direction belongs to strategy or goal clarification. Moving defined work to a better-placed owner is delegation, and creating a missing condition is prerequisite. If the parties agree but lack the skill to execute, use learning, and if the interface problem is really that nobody has decided what done means, use goal clarification first.

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

@@ -0,0 +1,37 @@
+# Creative Exploration
+
+## Description
+A creative-exploration suggestion deliberately widens the space of possibilities beyond the assumptions currently in play. It works by varying one input — audience, medium, constraint, sequence, scale, or definition of value — and reading off the options that variation makes visible. The output is a concrete set of meaningfully distinct possibilities, not an invitation to brainstorm, because an invitation produces more of whatever the group already thinks. Distinctness is the property that matters: options that differ in mechanism or in who benefits change a decision, and options that differ in wording do not. Novelty on its own is worthless here and is the main way the category gets wasted. What justifies the exercise is contrast that a later choice can act on.
+
+The exploration must be bounded or it becomes a detour with no return path. The suggestion should say how many options are enough to create contrast without generating noise, what time or attention budget contains the exercise, and what rule keeps familiar variants from filling the slate. It should name the criterion or signal that will identify a promising direction, because generating options without a selection rule simply relocates the difficulty. It should say how a selected idea comes back to the original goal or to a concrete test, since an unconnected idea is entertainment. It should also name the assumption being varied explicitly, so that the exercise can be repeated with a different one if the first pass yields nothing. Exploration that cannot state what it varied has not explored anything.
+
+## Why use
+Use this category when the option set is too narrow and everyone has stopped noticing. Groups converge, and convergence looks like agreement long after it has become a blind spot; the proposals all differ in detail and share a premise nobody has examined. In that state, evaluating the existing options more carefully cannot help, because the best available option may not be in the set. Widening the set first is the only move that changes the outcome, and it has to be done deliberately, since the natural drift is towards refinement.
+
+The category also buys insurance against premature narrowing. Early commitment is efficient when the field is well understood and expensive when it is not, and the cost of discarding an option before its value was visible is invisible by construction. A short, bounded exploration is a cheap hedge against that cost. Bounding it is what makes the hedge affordable, and it is why this category insists on a budget and a selection rule rather than treating open-endedness as a virtue.
+
+Keep the boundary against its neighbours clear. Alternative compares a small number of routes against a fixed outcome and is the right category once the aim is to choose rather than to widen. Cross-domain borrows a specific mechanism with evidence behind it from another field, which is a targeted transfer rather than a general expansion. Reframing changes the interpretation of the problem itself, producing one new reading rather than a slate of options. Big bets and long-term directions concern commitment and capability over time, not the generation of possibilities. Use creative exploration when the useful next act is to see more of the field.
+
+## Use cases
+- **Every current option looks alike.** Repeated proposals may share an assumption about audience, mechanism, or acceptable scope. Vary the assumption and produce options that could genuinely change the decision.
+- **A familiar solution pattern is exhausted.** Optimizing a route that no longer yields gains is a sign the route is the limit. Change the frame or the medium to expose a different mechanism.
+- **The beneficiary is defined too narrowly.** A different user, stakeholder, or setting may reveal an unmet need or a different value exchange. Use it when broadening the perspective yields testable options.
+- **Constraints are stopping ideas rather than shaping them.** A budget, deadline, policy, or resource limit may be treated as a reason not to think. Run a constrained exercise that turns the limit into a generator of distinct possibilities.
+- **Several futures need prepared responses.** Conditions may be unknown while the plausible responses are enumerable. Use the category when the exercise ends in a small option set tied to recognizable signals.
+- **A group is trapped in one vocabulary.** People may be unable to see options because everyone describes the problem the same way. Suggest a concrete reframing, analogy, or role shift that changes the available language.
+- **A little novelty would sharpen a test.** One unusual concept may point at a better experiment or interaction. Use it when a path back to the original goal exists and a selection rule is defined.
+- **Narrowing early is riskier than exploring.** A short session may preserve meaningful choice at negligible cost. Recommend it when the decision is not yet due and the field is poorly mapped.
+- **The same objection kills every proposal.** A recurring blocker may be a constraint worth designing against directly. Generate options that attack the constraint rather than avoiding it.
+- **The work has an unexamined default.** A format, channel, scale, or sequence may have been inherited rather than chosen. Vary the default explicitly and see what appears.
+- **A scarce resource is assumed fixed.** Time, attention, budget, or access may be treated as immovable when it is merely conventional. Explore options that change the resource rather than working within it.
+- **The problem is being solved at one scale only.** A much smaller or much larger version may have a different and better answer. Generate options at both extremes before returning to the middle.
+
+## When not to use
+- **A clear route already exists.** Widening the field when the choice is made wastes the decision's remaining time.
+- **No selection rule or boundary exists.** Options with no way to choose among them are noise with extra steps.
+- **The request is for more ideas with no decision attached.** Generation without a destination has no stopping condition.
+- **The novelty needed is a proven mechanism from elsewhere.** Borrowing a specific working pattern is a targeted act, not an expansion.
+- **Only one interpretation needs to change.** A single new reading of the problem is a different move from a slate of options.
+- **The decision is due now.** Exploration that arrives after the choice is made costs attention and returns nothing.
+
+Route the suggestion elsewhere when one of those signals holds. Execution belongs to continuation, and choosing among competing commitments belongs to prioritization. Comparing a few routes to a fixed outcome is alternative, and borrowing a tested mechanism from another field is cross-domain. Changing the interpretation of the problem is reframing, and testing whether one promising idea holds is experiment. If the exploration is stalling because nobody agrees what a good outcome looks like, use goal clarification first.

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

@@ -0,0 +1,37 @@
+# Cross-Domain
+
+## Description
+A cross-domain suggestion transfers a working mechanism from another field into the current problem. What is borrowed is causal structure — a pattern, a constraint, a practice, or a method — and not a memorable comparison. The source field must have evidence that the mechanism works in its own context, because an untested idea from elsewhere is simply an untested idea. The mapping has to be stated in both directions: which elements correspond to the current actors, constraints, and outcomes, and where the correspondence breaks because the contexts differ. That second half is what separates a transfer from an analogy, and it is the half most often omitted. A comparison that cannot say where it fails cannot be relied on where it holds.
+
+The suggestion should separate the portable principle from the domain-specific ritual around it, since most practices carry both and only one of them travels. It should name the new assumptions and risks that arrive with the transfer, because borrowed mechanisms bring borrowed failure modes. It should propose the smallest trial capable of testing whether the causal relationship survives the context change, rather than advocating adoption on the strength of the resemblance. It should say what result would justify adapting the transfer, narrowing it, or abandoning it, so the trial can actually conclude. Where the current problem is not defined well enough to compare contexts responsibly, the transfer cannot be evaluated and should not be proposed. A suggestion that only offers vocabulary from another field has moved words rather than mechanisms.
+
+## Why use
+Use this category when a field has been working on a problem long enough to exhaust its own solution family, and when another discipline has plausibly met the same structural problem under a different name. Queues, incentives, feedback loops, contention, learning curves, and coordination costs recur across domains with quite different surface descriptions, and the accumulated knowledge in one field is frequently decades ahead of another's on exactly the mechanism that matters. Borrowing it is cheaper than rediscovering it, and the discount is the argument.
+
+The category also does specific work against a failure that generic idea generation cannot address. Creative exploration widens the option space but draws its options from what is already imaginable within the current frame. A transfer imports something the frame does not contain, which is a different and often larger move. The discipline the category adds — name the mechanism, show the source evidence, map the correspondence, mark where it breaks — is what keeps this from degenerating into decorative metaphor, which is what happens to most cross-domain suggestions in practice.
+
+Distinguish it carefully from its neighbours. Creative exploration varies an assumption to generate distinct options without claiming that any of them has worked before. Reframing changes how the problem is understood using no external source at all. Learning builds a capability the caller lacks, which may be needed to execute a transfer but is not itself one. Alternative compares routes already available in the current field. Use cross-domain only when there is a real source, a real mechanism, and a mapping specific enough to be wrong.
+
+## Use cases
+- **The field keeps producing the same solution family.** A parallel discipline may have solved a structurally similar problem by another mechanism. Use the category when the borrowed mechanism would change the design space rather than decorate it.
+- **A process has a recognizable analogue elsewhere.** Queues, incentives, feedback loops, learning, and coordination appear across many domains. Suggest the transfer when the underlying relationship matters more than the surface resemblance.
+- **A mature practice could shorten discovery.** Another field may have established ways of observing, sequencing, training, or controlling a comparable system. Use it when the practice can be adapted without pretending the contexts are identical.
+- **Local vocabulary is obstructing the problem.** A source field may offer a more productive way to name the mechanism or its boundary. Recommend it when the new naming leads to a concrete question or action.
+- **A constraint resembles one handled well elsewhere.** Limited capacity, trust, attention, or reliability may have established treatments in another domain. Make the constraint mapping explicit rather than gesturing at similarity.
+- **A cheap probe could test an uncertain transfer.** The mapping may be plausible and unproven while the trial is inexpensive. Suggest it when the trial tests the causal mechanism rather than the surface effect.
+- **A practice is portable at the level of principle.** The original method may contain a reusable rule wrapped in context-bound ritual. Extract the principle and say explicitly which details are being discarded.
+- **Another field exposes a neglected failure mode.** Comparison may surface an assumption the current field never had reason to question. Recommend the transfer when it improves prevention, measurement, or choice.
+- **A measurement problem has been solved elsewhere.** Another discipline may already know how to observe the quantity that is currently being guessed at. Use it when the instrument, not the idea, is what transfers.
+- **A regulated or safety-critical field has a relevant discipline.** Fields with severe consequences often have rigorous practices for review, staging, or rollback. Borrow the practice when the consequence profile genuinely justifies it.
+- **An incentive structure keeps producing the wrong behaviour.** Economics, game theory, and mechanism design offer well-studied treatments for this. Suggest the specific mechanism, and say what it assumes about the actors.
+- **A scaling behaviour is already characterized elsewhere.** Another domain may know how the relevant quantity behaves as size grows. Use the known curve rather than discovering it empirically.
+
+## When not to use
+- **The comparison is decorative.** A metaphor that changes no decision costs attention and returns nothing.
+- **No source mechanism can be named.** Generic best practice with no origin is not a transfer.
+- **The current problem is too vague to map.** Contexts cannot be compared responsibly when one of them is undefined.
+- **The source evidence does not exist.** Borrowing an untested idea imports the risk without the discount.
+- **Where the analogy breaks cannot be stated.** An unfalsifiable mapping will be trusted exactly where it fails.
+- **The method is already adopted here.** Applying something established is execution, not transfer.
+
+Route the suggestion elsewhere when one of those signals holds. Generating possibilities without an external source is creative exploration, and changing the interpretation of the problem is reframing. Applying an already-adopted method is continuation or preparation, and acquiring the skill to apply it is learning. Comparing routes available within the current field is alternative, and testing whether a specific borrowed mechanism holds here is experiment. If the problem is not yet defined well enough to compare anything, use goal clarification first.

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

@@ -0,0 +1,37 @@
+# Delegation
+
+## Description
+A delegation suggestion moves a defined piece of work to the person or agent best placed to carry it. Its first act is a separation: judgment that must stay with the caller on one side, and execution, preparation, or information gathering that can move on the other. Work that has not been separated cleanly cannot be delegated, only shared, and shared work tends to return. The handoff must name the recipient, the expected result, the boundaries, the authority granted, and the path by which progress comes back. Delegation transfers execution responsibility while leaving the caller accountable for the outcome, and conflating those two is what makes delegation feel like abandonment to whoever receives it. Decisions that define quality, risk, or direction stay with the caller unless that authority is transferred on purpose.
+
+The suggestion must price the handoff honestly, because delegation is not free and is frequently proposed as though it were. Explaining, granting access, reviewing, and correcting all cost the caller's attention, and for small one-off tasks that cost exceeds simply doing the work. The relevant comparison is between the attention released and the attention spent, over the number of times the work will recur. The suggestion should name what the recipient needs in order to start, since a handoff missing its inputs converts into a stream of interruptions. It should define acceptance evidence that lets the caller review efficiently rather than re-perform the work. It should set a check-in cadence that observes progress without reclaiming execution, because the fastest way to un-delegate something is to supervise it continuously.
+
+## Why use
+Use this category when the caller's attention is the scarce resource and some of what is consuming it does not require the caller. This is the common shape of a person who has become a constraint on their own work: the decisions only they can make are queued behind execution anyone could do. The suggestion releases the scarce input, which is a larger effect than improving any individual task, and it is frequently invisible to the person inside the situation.
+
+The category also forces a specification that has value beyond the handoff itself. Writing down the expected result, the boundaries, and the acceptance evidence usually reveals that expectations were implicit, and implicit expectations are the actual reason work gets reviewed repeatedly. Once specified, the work can be delegated, automated, or repeated by the caller more cheaply than before. The specification cost is recovered whenever the work recurs, which is also the test for whether the delegation is worth proposing at all.
+
+Distinguish it from the categories nearest to it. Coordination resolves who owns a boundary between parties who are already both involved, where delegation assigns a defined unit of work to one owner. Bottleneck diagnoses a limiting point in a system, and centralized execution is one cause of that; delegation is a possible repair rather than the diagnosis. Learning builds a capability the caller or the recipient lacks, which is the right suggestion when no capable recipient exists. Prerequisite creates a missing condition, and the absence of a qualified owner is exactly such a condition. Use delegation when the work is separable, a suitable owner exists, and the attention released exceeds the cost of handing it over.
+
+## Use cases
+- **The caller is the scarce decision-maker.** Routine execution may be crowding out choices only the caller can make. Move the defined work and keep the governing decisions.
+- **Someone else has closer context.** A colleague, partner, or operator may be nearer to the users, the system, or the process. Suggest it when proximity improves execution and the expected result can be stated.
+- **An agent can perform bounded preparation.** Research, formatting, inventory, comparison, or drafting may need no judgment from the caller. Use it when the agent works within clear authority and returns inspectable evidence.
+- **Centralized execution is the constraint.** Too much work may be queued behind one person who does not need to perform every step. Recommend distribution when it relieves the constraint without creating coordination overload.
+- **The work recurs often enough to specify.** A repeating activity may justify a standard handoff, checklist, and acceptance condition. Use it when the specification cost is recovered across repetitions.
+- **Ownership would improve follow-through.** Work with no named executor lingers in the caller's mental queue. Assign a real owner with a commitment and an escalation path.
+- **Review is adding oversight but not value.** Repeated checking often reflects implicit expectations rather than necessary judgment. Propose a better contract that reduces the review loop.
+- **The work is a development opportunity.** A bounded responsibility may build someone's capability while advancing the task. Recommend it when the learning cost is acceptable and the risk boundary is explicit.
+- **The caller is the wrong person on skill grounds.** Another owner may simply do the work better, faster, or more safely. Say so plainly, and define what the caller still decides.
+- **Availability, not ability, is the constraint.** The caller may be capable and absent at the times the work is needed. Delegate for coverage, and define the authority that makes coverage real.
+- **A task is blocking the caller's own critical path.** A small piece of unrelated work may be holding up something only the caller can advance. Move the small piece rather than reordering the critical work.
+- **The work has an obvious natural owner nobody has named.** Responsibility may be clear to everyone and assigned to no one. Make the implicit assignment explicit, with its inputs and acceptance.
+
+## When not to use
+- **Judgment is required at every step.** Work that cannot be separated from the caller's decisions cannot be handed over.
+- **No responsible recipient exists.** Delegating to nobody in particular is a way of losing work.
+- **The handoff costs more than the task.** For small one-off work, explanation and review exceed execution.
+- **Accountability would become ambiguous.** A transfer that blurs who answers for the outcome makes things worse than doing nothing.
+- **The recipient lacks the capability.** Assigning work someone cannot do converts a task problem into a people problem.
+- **Ownership is contested among several parties.** Assigning a unit of work does not settle a boundary dispute.
+
+Route the suggestion elsewhere when one of those signals holds. A contested boundary belongs to coordination, and a missing capability belongs to learning or prerequisite. A limiting point in the system belongs to bottleneck, and competing claims on the caller's attention belong to prioritization. If the work is small and worth simply finishing, use completion or quick wins, and if it is not worth anyone's time, use stop or defer.

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

@@ -0,0 +1,37 @@
+# Experiment
+
+## Description
+An experiment is a bounded intervention designed to separate competing explanations, designs, or choices. Its worth is measured entirely by whether the result would change what happens next, which means a test whose every outcome leads to the same action is not an experiment but a formality. The intervention must be small enough to run reversibly and specific enough to produce evidence that can be interpreted without argument. It must name the uncertainty it addresses, because the most common failure in this category is a rollout described as learning. A rollout gathers data while committing; an experiment gathers data in order to decide whether to commit. The difference is whether the decision is still open when the result arrives.
+
+The suggestion should identify which competing accounts make different predictions, since discrimination between them is what the design has to achieve. It should name the baseline, comparison, or observation that makes the result interpretable, because a measurement with nothing to compare against usually confirms whatever was expected. It should specify enough sample, duration, or exposure for the question being asked, and admit when that is more than the situation can afford. It should constrain harms, spillovers, and irreversible commitments, since a test that damages what it was protecting has failed regardless of its result. It should set thresholds in advance for adoption, revision, further testing, and stopping, because effort already spent is the reason indefinite tests continue. It should state what the caller will do differently for each plausible result, and if that list has one entry, the experiment should not be run.
+
+## Why use
+Use this category when a decision is blocked by uncertainty that argument cannot resolve and evidence can. This is a narrower situation than it appears, because a great deal of hesitation is really about preference, authority, or unclear goals, none of which a test can settle. When the blocker genuinely is a fact about the world that nobody knows, an experiment converts an unresolvable debate into a scheduled answer, and that conversion is the most valuable thing the category offers.
+
+The category also buys down the cost of being wrong. A consequential choice made without evidence carries the full cost of reversal; the same choice made after a bounded test carries the cost of the test plus a smaller probability of reversal. Where that trade is favourable it is strongly favourable, and it is favourable most often when commitment is expensive and testing is cheap. Naming the loss limit, the exposure, and the stop rule is what keeps the test on the cheap side of that trade.
+
+Distinguish it from its close neighbours carefully, because they are routinely confused. Verification checks a claim believed to be true before something is relied on, which is a confirmation task rather than a discrimination task. Investigation gathers existing evidence to inform a decision without intervening in the world at all, and where the answer can be looked up, intervening is waste. Alternative compares routes by argument and is the right move when the distinguishing criteria are already known. Big bets concerns commitments too large for a test to substitute for, though staging often turns one into a sequence of experiments. Use experiment when a bounded intervention, and only an intervention, would change the decision.
+
+## Use cases
+- **Two explanations predict different outcomes.** Both accounts may fit the evidence available today. Design one bounded intervention whose result they disagree about.
+- **A consequential design choice is uncertain.** Full commitment may be costly or hard to reverse. Test the behaviour that matters before the decision becomes expensive.
+- **A new intervention needs evidence of effect.** The question may be whether a change improves a meaningful outcome at all. Use a comparison or baseline that makes the effect interpretable.
+- **A feasibility question blocks a larger plan.** The issue may be whether a capability, process, or constraint can work at all. Test the limiting condition rather than building the whole solution.
+- **A message or offer needs behavioural evidence.** Stated opinions may not predict whether people act, understand, or pay. Use a small exposure that measures the behaviour rather than the sentiment.
+- **A process change may carry hidden costs.** Faster or simpler work can affect quality, safety, workload, or downstream flow. Run a limited rollout that observes the intended gain and the most likely harm together.
+- **A stop rule is needed before more is invested.** Without a predefined threshold, a test continues because effort has already been spent. Define in advance what escalates, changes, or ends the effort.
+- **A trial preserves options while learning.** A low-exposure test may avoid premature commitment to one route. Recommend it when both the exposure and the interpretation are controlled.
+- **Estimates disagree by more than they should.** Two credible forecasts may differ enough that planning cannot proceed. Measure the quantity directly when measuring is cheaper than reconciling.
+- **A rare failure needs to be reproduced.** An intermittent problem may resist analysis until it can be triggered deliberately. Design the smallest intervention that provokes it under observation.
+- **A dependency's real behaviour is unknown.** Documentation, a vendor claim, or an assumption may not match practice under the conditions that matter. Probe it in the conditions that matter, not in general.
+- **A capacity or scaling limit is assumed rather than known.** The plan may rest on a number nobody has measured. Test at the boundary before designing around it.
+
+## When not to use
+- **The needed action is already known.** Testing a settled decision spends time buying nothing.
+- **The question is factual and answerable without intervening.** If it can be looked up, intervening is the expensive route.
+- **No result would change the decision.** A test with one possible consequence is a ritual.
+- **The proposal is an unbounded rollout.** Committing while measuring is not learning, whatever it is called.
+- **The check merely confirms an established claim.** Confirmation before reliance is a different discipline with different standards.
+- **The exposure cannot be constrained.** A test that risks the thing it protects has already failed.
+
+Route the suggestion elsewhere when one of those signals holds. Confirming a claim before relying on it is verification, and gathering existing evidence is investigation. Comparing known routes by argument is alternative, and choosing a coordinating direction is strategy. A commitment too large to be substituted by a test is big bets, and execution of a settled decision is continuation. If the uncertainty is about what people experience rather than what the system does, use feedback.

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

@@ -0,0 +1,37 @@
+# Feedback
+
+## Description
+A feedback suggestion seeks a specific reaction from someone positioned to notice what the caller cannot. It names three things: what to show, who should see it, and which question will produce a response worth acting on. The artifact has to be developed enough to reveal the behaviour or judgment in question, and honest enough about its own state that the reaction is about the work rather than about its polish. Timing matters as much as content, because a response that arrives after the decision is irreversible costs the reviewer's time and returns nothing. The category exists to import a perspective, not to distribute responsibility. A caller who already has the evidence needed to decide is not seeking feedback but company.
+
+The suggestion must distinguish decision-relevant signal from approval, since most unstructured requests for comment return politeness. The question should be shaped so that its answer is evidence: what the reader understood, where they hesitated, which interpretation occurred to them first, what they would do next. It should be clear in advance which responses would change the work and which would not, because a request that cannot be acted on is a request that should not be made. The suggestion should say how conflicting or biased responses will be interpreted, since averaging disagreement into consensus destroys the information that made the disagreement useful. It should name the revision window the response feeds, so the reviewer knows their effort has somewhere to go. It should also match the reviewer to the question, because expertise in one dimension does not transfer to another.
+
+## Why use
+Use this category when the limiting factor is a perspective the caller structurally cannot hold. Familiarity with one's own work removes exactly the information that matters most about how it lands: what is confusing, what is assumed, what a newcomer does first. No amount of care substitutes for this, because the blind spot is created by the knowledge that makes the work possible. Someone else's reaction is the only instrument that reads it.
+
+The category also front-loads a cost that otherwise compounds. Discovering a misunderstanding at the point of use is far more expensive than discovering it in a ten-minute conversation, and the gap grows with everything built on top of the misunderstanding in between. Recommending feedback early is usually a recommendation to pay a small, certain cost instead of a large, probable one. That argument is strongest when the artifact is mature enough to provoke a real reaction and early enough that reacting to it can still change something.
+
+Distinguish it from the categories it sits beside. Verification checks whether a claim is true, which is a question about the world rather than about someone's experience of the work. Investigation gathers facts that already exist somewhere, and if the missing information is factual rather than experiential, asking a person is the slower path. Experiment measures behaviour under a controlled intervention and is the right choice when what people say and what they do are likely to diverge. Goal clarification settles what the work is for, which must happen before a reaction to it can mean anything. Use feedback when the needed input is a judgment or an experience that only another person can supply.
+
+## Use cases
+- **A user may hit friction the caller cannot see.** Familiarity hides confusion, hesitation, and unmet need. Watch a representative interaction rather than inferring it.
+- **An expert can spot a consequential flaw early.** A reviewer with standing may see technical, legal, operational, or domain risk. Ask while the artifact is ready for that judgment and revision is still affordable.
+- **Several interpretations of the work are plausible.** A reaction shows whether the intended meaning or value lands. Ask which interpretation occurred, not whether the reader liked it.
+- **A stakeholder must accept a trade.** The caller may need to learn which cost, scope, or risk is tolerable to an affected party. Structure the conversation around a decision rather than ceremonial approval.
+- **A prototype needs an observed interaction.** Use may reveal what description cannot. Ensure the artifact captures the specific moment under discussion.
+- **A draft needs targeted critique.** One well-formed question outperforms an open call for comments. Specify what kind of response would change the next revision.
+- **Conflicting perspectives need structured comparison.** Different users, operators, or experts expose different constraints. Compare responses against explicit criteria instead of averaging them.
+- **Learning later would be expensive.** A short early review may prevent substantial rework. Recommend it when the target and the decision impact justify the interruption.
+- **An assumption about the audience has never been checked.** The work may rest on a belief about who uses it and why. Test the belief against someone who fits the description.
+- **The work will be handed to someone who was not consulted.** A future owner, operator, or maintainer may hold constraints nobody has asked about. Ask before the constraint becomes a defect.
+- **A decision has already been made and needs a red team.** Committed choices benefit from a reviewer asked specifically to find the failure. Frame the request as adversarial so politeness does not suppress it.
+- **Two internal parties disagree about what users want.** Opinion may have replaced evidence on both sides. Bring a real reaction into the argument rather than another round of assertion.
+
+## When not to use
+- **The evidence needed is already available.** Asking for a reaction to avoid deciding is delay wearing consultation's clothes.
+- **The audience cannot answer the question.** Standing in one domain does not transfer to another.
+- **The artifact is too vague to react to.** A response to something unformed reports the reader's imagination.
+- **The decision is already irreversible.** Feedback that cannot change anything spends goodwill for nothing.
+- **The missing information is factual.** Experience is the wrong instrument for a question that has a documented answer.
+- **The goal itself is disputed.** A reaction to work whose purpose is unsettled measures the disagreement, not the work.
+
+Route the suggestion elsewhere when one of those signals holds. A factual gap belongs to investigation, and a claim to be confirmed before reliance belongs to verification. Behaviour that must be measured rather than reported belongs to experiment, and an unsettled purpose belongs to goal clarification. If the caller has the evidence and is avoiding the decision, the useful category is prioritization or completion, and if the work simply needs to reach the person who will own it, use coordination.

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

@@ -0,0 +1,37 @@
+# Goal Clarification
+
+## Description
+A goal-clarification suggestion makes an ambiguous desired outcome precise enough to act on. Its central move is to separate the result the caller wants from the activity currently consuming their attention, because those two drift apart quietly and the drift is invisible from inside the activity. A useful clarification names the audience, the value, the scope, and the stopping point wherever those details would change what gets built. It works by exposing interpretations that lead to different work or different measures of success, since an ambiguity that all readings resolve the same way costs nothing and needs no attention. The test of a clarification is whether it would have changed a decision. If every interpretation produces the same next action, the goal was clear enough.
+
+Clarification is not a demand for certainty before anything can begin, and treating it that way turns a useful category into an obstacle. The suggestion should ask for the minimum additional precision that unblocks the next decision, not for a complete specification. It should name what evidence would show meaningful progress without requiring the outcome to be perfectly defined in advance. It should make value priorities explicit where speed, quality, cost, reach, safety, and learning are being traded silently, because an unstated hierarchy gets resolved by whoever acts first. It should give a stopping condition that makes the goal complete enough for this commitment, since open-ended standards invite unbounded polishing. It should also state which activity is being mistaken for the result, because naming that substitution is usually the whole of the insight.
+
+## Why use
+Use this category when the cost of proceeding is that the work might be excellent and wrong. Ambiguity about an outcome does not announce itself; it shows up later as a deliverable nobody wants, two teams building incompatible things, or a project that cannot end because nothing counts as finished. Each of those failures is expensive and each was cheap to prevent at the point where someone could have asked what success looks like. The category exists to make that question a normal move rather than an accusation.
+
+It is also the correct response to a particular kind of stuckness that looks like a planning problem. When a caller cannot choose among options, cannot tell when to stop, or keeps admitting new scope, the usual instinct is to plan harder. Planning harder does not help, because the missing input is not a route but a destination. Clarifying the outcome resolves all three symptoms at once, which is why it is worth checking for before reaching for prioritization, strategy, or alternative.
+
+Distinguish it from the categories it precedes. Prioritization chooses among commitments whose value is already understood, so it depends on clarity rather than supplying it. Strategy selects a direction that coordinates several actions, which presumes agreement about what the direction is for. Alternative compares routes to a fixed outcome, and without a fixed outcome the comparison is meaningless. Reframing changes how the problem is understood, which is a creative act, where clarification is a specifying one. Use goal clarification when a sharper statement of the outcome would visibly change the next decision.
+
+## Use cases
+- **The request describes activity, not a result.** The caller may be busy without knowing what change the work should produce. Name the outcome that makes the activity worth doing.
+- **Stakeholders mean different things by success.** Hidden disagreement produces parallel work that nobody accepts. Surface one shared outcome or an explicit trade.
+- **Scope keeps expanding.** New tasks get admitted because no boundary was ever drawn. State what is included, what is excluded, and what is sufficient.
+- **The beneficiary is unclear.** Work may be optimized for the wrong person or decision-maker. Clarify when naming who must benefit would change the solution or the measure.
+- **Nobody can tell when to stop.** Open-ended standards invite endless polishing or research. Define a recognizable threshold, acceptance condition, or review point.
+- **Competing interpretations imply different moves.** The same phrase may support incompatible plans. Ask the question that separates them before execution compounds the error.
+- **A broad goal is justifying unrelated work.** Loose language makes every nearby idea look relevant. Restate the central outcome so that unrelated work can be declined.
+- **A value hierarchy is being applied silently.** Speed, quality, cost, reach, safety, and learning may be traded without anyone saying which leads. Make the priority explicit when it determines the route.
+- **Success is stated as a number with no mechanism.** A target may exist without agreement on what would cause it. Clarify the outcome behind the metric before work optimizes the metric alone.
+- **The same work is being redone under a new name.** Recurring effort often signals that the finish condition was never agreed. Define it once rather than negotiating it each time.
+- **A constraint is being treated as the goal.** A deadline, a budget, or a compliance requirement may have displaced the outcome it was meant to protect. Restore the distinction.
+- **Handover keeps failing.** Receivers rejecting work is often evidence that acceptance was never defined. Establish it with the receiver before more is produced.
+
+## When not to use
+- **The outcome is already clear.** Re-specifying a settled goal delays work without improving it.
+- **The obstacle is execution, evidence, or capacity.** Precision does not help when everyone already knows what is wanted.
+- **Clarification would only delay a low-risk action.** For cheap reversible work, acting produces the clarity faster.
+- **Priorities conflict but the goal does not.** Competing clear goals is a different problem from one unclear goal.
+- **The route is disputed rather than the destination.** Disagreement about how is not ambiguity about what.
+- **Every interpretation leads to the same action.** An ambiguity with no consequence does not need resolving.
+
+Route the suggestion elsewhere when one of those signals holds. Competing commitments belong to prioritization, and a disputed route belongs to alternative or strategy. Missing facts belong to investigation, and a doubtful claim belongs to verification. A missing capability belongs to learning or prerequisite, and a small reversible action that would settle the question faster than discussion belongs to immediate next steps. If the problem is that the current framing itself is unproductive, use reframing rather than sharpening the framing that is failing.

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

@@ -0,0 +1,37 @@
+# Immediate Next Steps
+
+## Description
+An immediate-next-steps suggestion identifies an action the caller can take right now, from the state they are actually in. It works forward from what is true, available, and unresolved rather than backward from a plan, which is what separates it from continuation. No accepted plan is assumed to exist, and none needs to, because the claim is only that this particular move is available and worth making. Where several moves are available, the suggestion compares them and picks the one with the best immediate progress or information value. The action must be small enough to begin without another round of abstraction, since a step that requires planning to start is not immediate. Its purpose is to shorten the distance between what is known now and the next useful result.
+
+The suggestion should prefer reversible moves, because acting before the full path is designed is only safe when being wrong is cheap. It should check for the hidden prerequisite that would make the apparent next step premature, since the most common failure here is enthusiasm about a step that cannot actually begin. It should say what result determines whether to continue, redirect, or stop, so that acting early does not become acting blindly. It should avoid creating unapproved scope or irreversible commitment ahead of decisions that belong to someone else. It should name the larger planning question it is deliberately deferring, because deferral stated is a choice and deferral unstated is avoidance. Momentum is a legitimate reason to act only when the action produces evidence or progress rather than motion.
+
+## Why use
+Use this category when the caller is stuck at an abstraction boundary — they know roughly what they want, and every route to it dissolves into more planning. In that state, further design does not help, because the information required to design well does not exist yet and will only be produced by contact with the problem. One small concrete action changes the state enough to generate a better question, and that is often worth more than an hour of thought. This is the specific situation the category is for.
+
+It also answers a practical constraint that the more architectural categories ignore: planning has a cost and a caller's attention is finite. Where a move is cheap, reversible, and informative, taking it is usually superior to reasoning about it, and the comparison is not close. The discipline the category adds is that the move must be chosen rather than grabbed — the best available action by progress or information value, with an explicit check for the prerequisite that would make it premature.
+
+Distinguish it from the categories nearest to it. Continuation presumes an accepted plan and advances it, which is the right category whenever such a plan exists, since the next step is then already determined. Investigation gathers evidence deliberately to inform a decision, whereas an immediate next step may produce evidence as a side effect of doing something useful. Quick wins argues from cheap payoff rather than from availability, and an immediate next step may have no payoff of its own beyond moving the state. Goal clarification applies when the destination is too vague for any action to be evaluated, which is a prior condition rather than a competing option. Use immediate next steps when something useful can start now and starting is better than deciding.
+
+## Use cases
+- **Nobody knows what can begin.** The current state may already support one useful action even with the plan incomplete. Turn availability into a concrete start.
+- **Several cheap actions are possible.** Choosing one reduces delay and avoids more abstract planning. Pick the move with the strongest immediate progress or information value.
+- **The next action would reveal the problem's shape.** A small inspection, conversation, draft, or measurement may make later choices easier. Use it when the action is safe and its result informs what follows.
+- **The caller is stuck at an abstraction boundary.** Broad goals can hide the first observable operation. Name an action that changes the state enough to produce a better question.
+- **A new task has no accepted route.** The direction may be plausible while the path stays open. Identify a reversible first move without pretending the plan is settled.
+- **A dependency may already be available.** Work may be delayed on an assumption that access, approval, or input is missing. Suggest checking, when confirmation would unlock work immediately.
+- **The move needs no new authority.** A small action may produce progress while larger decisions wait for an owner. Use it when nothing irreversible or out of scope is created.
+- **Momentum would help and is cheap.** Starting may reduce context-switching and make the task concrete. Recommend it only when the motion produces evidence or progress.
+- **The context is about to be lost.** A person, an environment, or a state may be available now and gone shortly. Act while the conditions hold.
+- **The work has stalled on a decision that does not block everything.** Part of the effort may be independent of the open question. Start the independent part, and name what still waits.
+- **The first step is obvious but has never been said out loud.** Groups stall on steps everyone assumes someone else identified. Say it plainly, with an owner.
+- **A five-minute action would replace an hour of speculation.** A quick check may settle an argument nobody can resolve by reasoning. Recommend the check rather than the discussion.
+
+## When not to use
+- **An accepted plan already determines the next step.** Rediscovering a step the plan contains wastes the plan.
+- **A required condition is missing.** An action that cannot start is not immediate, however appealing it looks.
+- **The step forces a consequential decision.** Acting early must not pre-empt a choice that belongs to someone else.
+- **Broad alignment has to happen first.** Starting ahead of agreement creates work that will be undone.
+- **The goal is unclear.** An action cannot be the best available move when nobody can say what better means.
+- **A fact must be established first.** Acting on an unchecked belief converts uncertainty into rework.
+
+Route the suggestion elsewhere when one of those signals holds. An accepted plan belongs to continuation, and a missing condition belongs to prerequisite. An undefined outcome belongs to goal clarification, and a fact that must be settled first belongs to investigation or verification. Alignment among parties belongs to coordination, and a consequential open choice belongs to alternative, strategy, or prioritization depending on its scope. If the attraction of the step is its cheap payoff rather than its availability, the honest category is quick wins.

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

@@ -0,0 +1,37 @@
+# Investigation
+
+## Description
+An investigation gathers missing knowledge that a consequential action or decision depends on. It begins with a precise question and ends when the evidence available is sufficient for the decision at hand, which is a much lower bar than sufficient in general. The distinguishing feature is that the answer already exists somewhere and needs to be found rather than produced, which is what separates this category from experiment. Sources should be chosen for authority, accessibility, currency, and relevance, in proportion to what the decision is worth. More information is not automatically better, and information that cannot change the decision is a cost with no return. An investigation without a named decision behind it has no way to know when it is done.
+
+The suggestion should say what evidence would be sufficient rather than merely interesting, because that distinction is the only defence against research that expands to fill available time. It should say how source quality, definitions, and conflicts will be evaluated, since disagreement between sources is usually a definitional problem rather than a factual one. It should exclude information with low decision value explicitly, as the instinct to be thorough is what turns a two-hour question into a two-week one. It should include a stopping rule and a synthesis format, so that what was learned survives as something other than open tabs. It should say how the findings will change the next action or the caller's confidence, and if neither would move, the investigation should not be run. Where the stakes are low and the action is reversible, acting is frequently the cheaper way to learn.
+
+## Why use
+Use this category when information is the binding input to the next choice — not execution, not persuasion, not alignment, but knowing something that is currently unknown. This is worth checking deliberately, because the felt experience of being blocked by uncertainty is very similar to the felt experience of being blocked by indecision, and only one of them is helped by research. When it genuinely is information, a short, targeted inquiry is among the highest-return actions available, since it can prevent a commitment made on a false premise.
+
+The category also exists to discipline research that has stopped being useful. Open-ended reading feels productive, produces a legible artifact of effort, and defers the decision indefinitely, which makes it the most comfortable form of avoidance available to a capable person. Requiring a question, a source set, a sufficiency threshold, and a stopping rule converts that into bounded work. The requirement to name what would change as a result is the sharpest of these, because it fails immediately for investigations whose real purpose is delay.
+
+Distinguish it from its neighbours. Experiment intervenes in the world to produce evidence that does not yet exist, and intervening is the wrong move whenever the answer can simply be found. Verification checks a specific claim believed true against a known acceptance condition, which is narrower and usually faster. Learning builds a durable capability rather than answering one question, and the two are confused whenever a question is large enough to feel like a subject. Feedback collects a judgment or an experience from a person, which is the right instrument when the missing input is not a fact. Use investigation when the fact exists, matters, and is findable.
+
+## Use cases
+- **A consequential decision rests on a missing fact.** Acting without it may create material cost, risk, or rework. Gather only the evidence that bears on the decision.
+- **Sources disagree about an important claim.** Conflicting information may change the route or the confidence behind it. Compare source quality, definitions, timing, and evidence rather than counting opinions.
+- **The current state is not known.** An inventory, baseline, dependency map, or history may be missing. Use it when the snapshot will determine a concrete action or allocation.
+- **A constraint or requirement is unclear.** Policy, law, contract, platform behaviour, or stakeholder need may govern what is possible. Identify the governing source and apply it.
+- **A pattern needs explanation before intervention.** Repeated behaviour may have several candidate causes. Gather discriminating evidence rather than choosing a remedy immediately.
+- **An external option must be compared.** Vendors, methods, markets, or practices may differ on criteria that matter. Bound the comparison frame and set the decision threshold in advance.
+- **The cost of being wrong is high.** A short evidence-gathering step may protect a much larger commitment. Use it when the inquiry materially lowers uncertainty before exposure grows.
+- **Research is running without a stopping rule.** Open-ended reading can defer action while feeling productive. Impose an explicit question, source set, synthesis format, and evidence threshold.
+- **A number is being assumed rather than known.** Cost, volume, latency, or capacity may have entered the plan as a guess. Establish the real figure when the plan is sensitive to it.
+- **Prior work on this problem may already exist.** Someone inside or outside the organization may have answered this already. Check before rediscovering it at full price.
+- **A claimed constraint may not be real.** A rule, a limit, or an impossibility may be folklore rather than policy. Find the source, and read it.
+- **The decision needs history, not analysis.** Understanding why something is the way it is may be the only route to changing it safely. Recover the rationale before proposing a replacement.
+
+## When not to use
+- **The evidence is already available.** Re-gathering what is known spends time to produce nothing.
+- **The answer must be produced rather than found.** Where no source can hold it, intervention is the only route.
+- **No plausible finding would change the decision.** Research that cannot move the choice is deferral.
+- **The claim has a known acceptance condition.** A targeted check is faster than an inquiry.
+- **The gap is a capability, not a fact.** Knowing about something is not the same as being able to do it.
+- **The action is cheap and reversible.** Doing it may answer the question faster than reading about it.
+
+Route the suggestion elsewhere when one of those signals holds. Producing new evidence by intervening belongs to experiment, and confirming a specific claim belongs to verification. Building a durable capability belongs to learning, and collecting a person's judgment or experience belongs to feedback. A cheap reversible action that would settle the matter belongs to immediate next steps, and an unclear outcome that makes every finding ambiguous belongs to goal clarification.

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

@@ -0,0 +1,37 @@
+# Learning
+
+## Description
+A learning suggestion targets the knowledge or skill that will improve a specific upcoming task. It must be tied to an application, because learning detached from use is indistinguishable from an interesting detour and consumes the same time. The smallest useful lesson beats a broad curriculum almost always, since the curriculum defers the application that would have shown which parts mattered. What justifies the category is a capability gap rather than an information gap: the caller does not merely lack a fact, they cannot yet do the thing. Repeated difficulty with the same operation is the clearest evidence that the gap is durable and worth closing rather than working around. A single hard task is usually cheaper to get help with than to learn.
+
+The suggestion should name the upcoming task or decision that will apply the learning, so the lesson has a deadline and a test. It should specify how understanding will be checked through practice, explanation, or a completed application, because reading and watching reliably produce confidence without capability. It should identify a source suited to the level of need rather than the most comprehensive one available. It should say what can be deferred until after the immediate commitment, since the instinct to learn the whole subject is what turns a two-hour gap into a two-week project. It should say what future action, judgment, or independence should improve, which is the only way to tell afterwards whether the investment paid. Where no application and no proof of understanding can be named, the suggestion is curiosity rather than learning.
+
+## Why use
+Use this category when the limiting factor is what the caller can do rather than what they know or have decided. That distinction matters because the repairs are different: a fact can be looked up in minutes, while a capability requires practice and a feedback loop. Treating a capability gap as an information gap produces a caller who has read about the thing and still cannot do it, which is a worse position than before because the gap is now hidden under the impression of preparation.
+
+The category also makes a claim about economics that deserves to be explicit. Learning costs time now to reduce cost later, so it is justified by repetition, by the rising cost of dependence, or by the quality of judgment it enables. Where the work happens once and help is available, the honest answer is to get help. Where the same operation recurs, or where relying on others is producing delay and coordination burden, the investment repays and should be named as an investment with an expected return rather than as self-improvement.
+
+Distinguish it from the categories around it. Investigation answers a question; learning builds the ability to answer that class of question unaided. Prerequisite creates a missing condition and is the right category when the capability is needed immediately and cannot be built in time, since someone else must then supply it. Delegation moves the work to someone who already has the capability, which is frequently the correct alternative to learning and should be compared honestly against it. Leverage captures a reusable organizational asset, where learning improves a person. Use learning when the caller will do this kind of work again and being able to do it themselves is worth the time.
+
+## Use cases
+- **The same capability gap recurs.** The caller may keep relearning or requesting help for one important operation. Build the skill when it will improve several upcoming attempts.
+- **An upcoming decision needs domain understanding.** The caller may not know which evidence, trade, or mechanism matters here. Use a focused lesson when it would materially improve that decision.
+- **A tool or method is blocking independence.** The caller may be unable to inspect, create, or change the work without assistance. Use it when a bounded practice path removes the dependency.
+- **A mistake exposed a durable lesson.** The specific error may be fixed while the pattern behind it remains. Extract and practise the principle when that is worth more than the patch.
+- **A new responsibility is arriving.** The caller may soon own a process, system, or conversation they have never handled. Build real competence rather than collecting material.
+- **One concept would unlock a concrete task.** A single technique or workflow may be all that stands in the way. Choose the smallest lesson whose application is observable in the task.
+- **Dependence is becoming expensive.** Relying on others may be producing delay and coordination burden. Internalize the capability when it improves judgment or execution enough to repay the cost.
+- **A learning path needs proof of understanding.** Reading alone reliably produces false confidence. Require practice, explanation, or a completed application as the check.
+- **The caller cannot evaluate work they are responsible for.** Accountability without competence turns review into rubber-stamping. Learn enough to judge, even if not enough to build.
+- **A shared vocabulary is missing.** The caller may be unable to participate in decisions because the terms are opaque. Target the vocabulary needed for the conversation, not the field.
+- **An assumption cannot be checked without the skill.** The plan may rest on a belief the caller has no way to evaluate. Learn the minimum required to test it.
+- **A recurring workaround signals a missing fundamental.** Persistent improvisation often marks a concept nobody has learned. Name the concept and close it once.
+
+## When not to use
+- **The gap is a fact.** A question with a findable answer does not require building a capability.
+- **Someone else must supply the condition.** A capability needed immediately and unavailable is a dependency, not a lesson.
+- **Learning would only delay a safe action.** For cheap reversible work, doing it teaches faster than studying it.
+- **No application can be named.** Without a task to apply it to, the lesson has no deadline and no test.
+- **No proof of understanding is possible.** Learning that cannot be checked will be assumed rather than acquired.
+- **The work happens once and help is available.** Building a skill for a single use rarely repays the time.
+
+Route the suggestion elsewhere when one of those signals holds. A findable fact belongs to investigation, and a claim to confirm belongs to verification. A condition that must exist before work proceeds belongs to prerequisite, and moving the work to someone already capable belongs to delegation. A reusable organizational asset belongs to leverage, and a capability worth growing over an extended horizon belongs to long-term directions. If a cheap action would teach more than study would, use immediate next steps.

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

@@ -0,0 +1,37 @@
+# Leverage
+
+## Description
+A leverage suggestion creates one asset or improvement that benefits several credible future efforts. Its value comes from reuse, from reduced coordination, from accumulated knowledge, or from a recurring cost that stops recurring. What makes it credible is named downstream consumers with near-term needs, not an argument from scale that nobody has checked. The pattern being generalized has to be visible in work that has already happened, because a shared abstraction built before the shared pattern appears will encode the wrong seam and cost more than it saves. Maintenance, ownership, documentation, and adoption are part of the investment rather than free consequences of building it. An asset with no owner decays into an obstacle that everyone routes around.
+
+The suggestion should name the smallest reusable form that solves the observed repetition, since the temptation in this category is to build the general case rather than the shared one. It should say who owns maintenance, access, and eventual retirement, because assets that cannot be retired accumulate indefinitely. It should account for adoption and migration effort, which regularly exceeds construction effort and is the most common reason a good shared asset produces no benefit. It should say how reuse and payback will be observed over time, so that the investment can be judged rather than assumed. It should state the evidence that the pattern is stable, because generalizing an unstable pattern locks in a shape that the next requirement will break. Where the consumers cannot be named, what is being proposed is speculation with a build cost.
+
+## Why use
+Use this category when the same work keeps being done and the repetition is visible in the record rather than in an intuition. Repeated effort is a tax that nobody notices individually, because each instance is small and each is justified on its own terms. Aggregating it is the insight, and once aggregated the case for a shared asset is usually obvious and was previously invisible. That aggregation is something a suggestion agent can do and a person inside the work usually cannot.
+
+The category also carries an unusual discipline: it argues for *delaying* generalization until the pattern is real. Most advice about reuse is enthusiastic about it, which is why so much premature abstraction exists. The honest position is that reuse has a cost curve — build, maintain, document, migrate — and that the curve is only favourable when the consumers are real and the shape is stable. Insisting on named consumers and observed repetition is what keeps this category from becoming a licence to build infrastructure nobody asked for.
+
+Distinguish it from its neighbours. Simplification removes complexity from the current result and may reduce reuse rather than create it, so the two can point in opposite directions. Long-term directions builds capability for a future that is not yet specified, whereas leverage requires specific near-term consumers. Preparation builds readiness for one anticipated event rather than for many recurring ones. Delegation moves work to another owner without making it cheaper to do. Use leverage when one bounded effort demonstrably improves more than one future task, and someone will own the result.
+
+## Use cases
+- **The same work is being repeated.** Research, setup, explanation, or transformation may recur across tasks. Build the shared asset when the pattern is stable enough that reuse exceeds maintenance.
+- **Several future users need the same evidence.** A durable record, dataset, decision log, or reference may prevent duplicate discovery. Use it when the consumers and the access path are both credible.
+- **A common interface would reduce coordination.** A template, contract, convention, or reusable workflow may ease future handoffs. Use it when the interface solves a repeated boundary problem rather than adding ceremony.
+- **An early artifact can become a building block.** Current work may yield a component, example, or capability that later tasks extend. Preserve the seam now when reconstructing it later would cost more.
+- **Learning can compound across tasks.** A documented principle, measurement, or postmortem may improve several future decisions. Use it when the lesson is specific enough to apply and verify elsewhere.
+- **A small investment removes a recurring cost.** Automation, indexing, standardization, or precomputation may repay over many uses. Check that the frequency and count actually support it.
+- **Consistency matters and varies.** Shared checks, examples, or defaults may reduce variation across related work. Use it when a clear owner will maintain them.
+- **The current change creates a reusable capability.** A new permission, integration, measurement, or process may serve more than its original purpose. Recommend it when the additional consumers have specific near-term needs.
+- **Onboarding keeps costing the same conversation.** The same explanation repeated to each new participant is a durable, measurable cost. Capture it once, and say who keeps it current.
+- **A scarce expert is the only route to a routine answer.** One person may be repeatedly consulted for something that could be written down. Externalize the knowledge rather than scaling the person.
+- **Several teams are independently solving one problem.** Parallel effort on the same need is repetition across space rather than time. Consolidate when the requirements genuinely coincide.
+- **A manual step precedes every instance of the work.** Setup, cleanup, or conversion may be paid on every run. Remove it once when the run count justifies the build.
+
+## When not to use
+- **The task is a one-off.** Reuse cannot repay an investment that is never reused.
+- **The consumers cannot be named.** A hypothetical audience is not evidence of demand.
+- **The pattern is still moving.** Generalizing an unstable shape locks in the wrong seam.
+- **Generalization would slow the current work.** Paying the abstraction cost before the second use is usually a loss.
+- **Nobody will own the asset.** An unmaintained shared asset becomes an obstacle rather than a benefit.
+- **Adoption cost exceeds the saving.** An asset nobody migrates to delivers none of its promised return.
+
+Route the suggestion elsewhere when one of those signals holds. Removing complexity from the current result belongs to simplification, and readiness for one anticipated event belongs to preparation. A capability worth developing over an extended horizon without named near-term consumers belongs to long-term directions, and moving work to a better-placed owner belongs to delegation. If the repetition is really a limiting point in the flow, use bottleneck, and if the pattern is not yet understood well enough to generalize, use investigation first.

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

@@ -0,0 +1,37 @@
+# Long-Term Directions
+
+## Description
+A long-term-direction suggestion identifies a capability, body of work, market, or relationship worth developing over an extended period. It is broader than the next task and still tied to a meaningful goal or a durable opportunity, which is what keeps it from being an aspiration. The horizon is its defining property: the value arrives slowly, compounds, and cannot be obtained by concentrating effort in a short window. That shape obliges the suggestion to acknowledge uncertainty, investment, and opportunity cost rather than treating the future as a place where things simply work out. The direction must also survive the possibility that conditions change, since a horizon long enough to compound is long enough for assumptions to expire. Long-term value is not a licence for vague ambition and does not remove the need to make present choices well.
+
+The suggestion should say what current evidence supports the direction without claiming that evidence proves it, because the honest epistemic state here is usually suggestive rather than conclusive. It should name the investment and the maintenance the direction will require, and say what is not being done instead. It should identify which assumptions are most likely to change over the horizon, since those are what the review should watch. It should offer a near-term signal capable of testing whether continued pursuit remains sensible, because a direction with no leading indicator cannot be abandoned on evidence and will therefore be abandoned on mood. It should name the review date and the criteria that apply at it. It should also say which options today's choices are preserving or foreclosing, since the cheapest form of this category is often simply not closing a door.
+
+## Why use
+Use this category when the useful observation is about a horizon rather than an action. Some of the most consequential things a caller can be told are not tasks: that a capability now nice to have will be structural in two years, that a relationship needs lead time nobody is giving it, that today's convenient choice quietly forecloses a route worth keeping. None of these fit as a next step, and compressing them into one misrepresents both the timescale and the certainty.
+
+The category earns its place by making patience accountable. Long-horizon investments fail in two symmetrical ways: abandoned too early because no signal was defined to justify continuing, or continued too long because no signal was defined to justify stopping. Requiring a leading indicator and a review date fixes both. It converts an open-ended commitment into a conditional one, which is the only honest form a long-horizon commitment can take when the assumptions behind it will certainly move.
+
+Distinguish it from the categories nearest to it. Strategy chooses a direction that coordinates several actions now, so it implies present subordination rather than patient development. Big bets asks for a large, concentrated, partly irreversible commitment, and calling such a commitment a direction understates the decision being made. Leverage requires specific near-term consumers, whereas a long-term direction is defined by the absence of those. Preparation builds readiness for one anticipated event with a known shape. Use long-term directions when today's actions can preserve or create a future option worth reviewing later.
+
+## Use cases
+- **A capability will matter across many future decisions.** Depth may serve better than solving each instance locally. Use it when the capability has a credible connection to future demand.
+- **A durable market or audience is emerging.** Early signals may justify exploring before the opportunity becomes a project. Monitor it without pretending the outcome is settled.
+- **Relationships need lead time to compound.** Trust, partnerships, communities, or institutional access cannot be built inside one task. Use it when the patient investment has a specific future value and a review path.
+- **Current work can preserve a strategic option.** A small choice today may keep a future route open cheaply. Recommend it when preservation is deliberate and creates no distracting commitment.
+- **Incremental work is hitting a durable ceiling.** Local improvement may not create what the next stage requires. Use it when only a broader development path changes the ceiling.
+- **The horizon is being ignored.** A narrow focus may neglect a future condition that already shapes present choices. Surface it when it informs today's trades without replacing them.
+- **Knowledge or assets can compound.** Repeated observations, tools, or experiments may accumulate into a real advantage. Use it when the accumulation has an owner and a plausible path to use.
+- **Investment should be conditional.** The direction may deserve pursuit under review rather than indefinite commitment. Name the leading indicators and the reassessment date.
+- **A dependency is becoming structural.** Reliance on a platform, supplier, or standard may deepen until it cannot be changed. Raise it while substitution is still affordable.
+- **A skill base is aging.** The capability that made the current work possible may be declining in relevance or availability. Start the replacement before it becomes urgent.
+- **A slow-moving external trend affects the plan.** Regulation, demographics, cost curves, or infrastructure may shift the ground over years. Track it explicitly rather than reacting late.
+- **A current shortcut will compound into debt.** A convenient choice may accumulate cost that only becomes visible at scale. Name the trajectory, and the point at which it must be addressed.
+
+## When not to use
+- **A concrete action is what is needed.** A horizon does not help someone who needs to know what to do today.
+- **A decision must be made now.** Deferring to a review date is not an answer to an urgent choice.
+- **There is no evidence, investment logic, or review signal.** Ambition with none of these is not a direction.
+- **The choice coordinates several immediate actions.** Present subordination is a different commitment from patient development.
+- **A large concentrated commitment is required.** A bet framed as a direction hides its exposure.
+- **Specific near-term consumers exist.** Named demand now is a reuse argument, not a horizon argument.
+
+Route the suggestion elsewhere when one of those signals holds. A coordinating present direction belongs to strategy, and a large uncertain commitment belongs to big bets. Named near-term consumers belong to leverage, and readiness for one anticipated event belongs to preparation. An urgent decision among competing commitments belongs to prioritization, and a concrete available action belongs to immediate next steps. If the direction rests on a belief nobody has checked, use investigation before proposing the horizon.