/product-principles

name: product-principles
description: 'Product principles for manifest-dev: how its maintainer wants calls about what the plugin does for its users made, and why. Use before planning, designing, building or reviewing a skill step, a mode, a default or an offer that manifest-dev ships.'

Edit rule: each line is a principle with its reason and when it yields. Decisions go to the decision records, rules a check can hold go to the check, and a line is added only on a person's yes, after sharpening an existing line is ruled out.

• When a call shapes behavior manifest-dev ships — a skill step, a mode, a default, an offer — prefer a sensible default every user gets with no setup, changeable through channels people already use (their stated rules, their context file, their project's own copy of a convention, a note at invocation), worded to hold across the many kinds of project the plugin runs in rather than one project, host or case — in the maintainer's words, "have defaults baked in with options to change and override, and keep things general when possible, since the product here applies to many, many use cases." A mechanism that serves one setup, or whose benefit nobody has isolated, stays out of the shared skill: it adds constraints and complexity every user inherits. Yields when no single default fits a known group of users: let the default follow what the session can see, rather than adding a setting or a question — a person who does not know a flag, mode or skill exists gets the wrong default anyway — and have the run say which it took and why, so plain words change it; and when generalizing would widen the work beyond the job at hand: generalize the wording, not the machinery.
• Ask a person for, and hand a person, only what is theirs — a cost to weigh, a change to what they agreed, a direction, a choice they kept — and let the run settle the rest and report what it chose and why, so one word redirects it; a run started unattended never asks and never waits, and puts the calls that were the person's first in its report — a person's yes does not scale to many agents, a stalled run costs closer to lost days than the minutes a question takes, and a report that floods stops being read. Yields when going on needs knowledge, access or authority the run lacks, or when a project's own rules ask for a person.
• Judge a skill step, a default or a new surface by whether it leaves less for a person to do next time: what a person answers once is kept where later runs load it (a principles line, a Taste entry, a decision record, the project's own files) so no run asks it again, and the steps before execution are built to need the person less as that record grows — in the maintainer's words, the goal is "to help minimize the human in the loop as much as we can the more you go up the layers" — an answer that lives only in a conversation is asked again by the next run, and a person's yes does not scale to many agents. Yields for the ends and bounds a person keeps, and for the person's own view, which is written only on their yes.
• What a skill writes for a person is budgeted by that person's attention: one claim per message, common words, the ask set apart with the answer the run would give, and nothing posted that changes nothing for its reader — no bookkeeping output, no repeat of an unchanged item, no question already answered — a correct message that arrives as a dense wall has not produced shared understanding, and repeats bury what is new. The load comes off how it reads, never off what was investigated. Yields to the person's own style instructions.
• Size what a skill spends — re-checks, recall, review passes, questions — to what rides on the ask, and write each such rule with the condition it fires under, never "on every run" — on a cheap, reversible ask the check costs more than a miss, and unconditional rigor made small asks worse. Yields when acting on the result would be costly or hard to undo: then full depth.
• Nothing the workflow relies on may depend on a person remembering to run it, on a schedule, or on infrastructure the user must set up: put it where a step people already run reaches it, and let upkeep ride the normal runs that touch a surface — a pass someone must remember does not run in practice, and nothing fails visibly when it is missing. Yields for an optional extra the workflow never depends on, and for a repair that is a project of its own, which is named as debt.
• Nothing binds a run that nobody with authority asked for, and nothing a person deliberately required is relaxed by the run that must meet it: a number, proxy or stricter bar an agent introduced stays revisable or becomes a question, and trying, repairing and size are bounded by evidence, never by a count or threshold nobody can source — an invented value read cold becomes a requirement nobody checked, a count misjudges both ways, and a run that may lower its own bar will. Yields when a person states the number: then it binds.
• What a skill keeps or acts on as the person's own view — a preference, a reason, a principle, a North Star position, a seeded term — is shown to them and written only on their yes to the exact text, or on a yes they gave in advance for a named run, which shows each line it wrote in its report; evidence may lower a line's confidence or flag it, and a run with no person present flags and writes nothing — an inferred reason can only be obeyed, not weighed, and it stops the pushback that would correct it. Yields when an assignment explicitly delegates that decision; never for an end or a principle.
• A choice the person will judge by seeing or using it — a look, a flow, a format — reaches them as concrete options or a rendered draft to react to, never decided silently inside a proposal or asked in the abstract — agreement in prose hides divergence, and a wrong concrete thing surfaces disagreement faster than a vague correct sentence. Yields: a rendering is offered, never pushed.
• W