How to shape a feature intent in an app repo

Use this when: You have an idea or request at app scale (one repo, one feature) and want to turn it into a spec your delivery loop can build — without skipping framing, de-risking, and decomposition. Prerequisites: product-engineering pack installed; an app-scale repo with app code; a feature idea, request, or brownfield context to shape. Result: A de-risked feature intent routed directly to one core spec when it is independently shippable, or to a coordinating brief when several specs or repositories need a shared envelope, ready for new-spec, author-delivery-brief continue, and work-loop.

Note

Diátaxis: how-to. A goal-oriented walk through the product-engineering loop at app scale (one repo, one feature). For the why, see the explanation The intent tree; for fields, the reference Intent fields and modes. For business-unit / cross-component shaping (a capability across many component repos), see the how-to Run a capability across a value stream.

You have an idea or a request and you want to turn it into a spec your delivery loop can build, without skipping the thinking. Install the product-engineering pack, then:

Shape this feature intent: workspace owners need export retention controls so compliance requests no longer require manual work.

Note

Starting higher than a feature. This walkthrough shapes a feature intent, but Level is an open set (product-vision › product-strategy › capability › feature) and is no longer stamped from Scale. An app-scale greenfield product concept — where the real question is “should this product exist at all” — can start at a product altitude (product-vision), not only at feature; for that route see Frame a product vision and Shape a product strategy. intent frame asks the altitude for concept-shaped input; Scale only suggests a starting point you override in a word. The rest of the loop (de-risk, decompose) is the same shape at any level.

1. Frame the intent

Invoke intent frame. It runs intake first: it infers Scale (one repo with app code → app), confirms it, and asks whether this work is greenfield or brownfield. Then you fill an intent (the skill ships the template at intent/assets/intent-template.md; copy it to docs/product/intents/<slug>.md):

• Outcome — a steerable input metric, the lagging outcome it should drive, and a guardrail that must not get worse. In 0-to-1, a qualitative-but- falsifiable outcome is fine.
• Opportunity — what the user is trying to get done, framed without a solution. In brownfield you may pull in a journey or process map; in greenfield, skip them.
• Assumptions — what must be true for the bet to pay off, one line each.

JTBD enrichment in the Opportunity

intent frame step 5 prompts for all four dimensions of the opportunity using a three-tier JTBD model. Fill each into the intent’s optional Opportunity sub-fields:

• Functional job: what the user is trying to accomplish, independent of any solution — “get back into my account on my own without waiting for a support queue.”
• Emotional job: how they want to feel during or after the job — “feel in control of the situation, not at the mercy of a slow email link.”
• Social job: how they want to be perceived by others — “be seen as self-sufficient and capable by my team.”
• Struggling moment: where today’s situation fails them — “when locked out, the reset-link email arrives minutes late — so the user is stuck with no progress signal.”

Free-form prose in the Opportunity section remains valid — use the sub-fields when the opportunity is job-shaped and you want all three dimensions captured. For a deeper pass that surfaces and scores every job behind the opportunity area, run identify-opportunities after framing.

intent frame is knowledge-surface aware: when an internal knowledge surface is reachable (an enterprise-knowledge MCP tool, an internal CLI, an in-repo doc set), it consults the business-domain and meaning areas so the outcome and opportunity use your org’s real terms and rules instead of generic ones, and it states which surface it used — or “none”, with the confidence lowered to match.

When the feature materially affects a human-facing surface, intent frame can add an optional Product-to-experience handoff to the same intent. It carries only product facts: the affected journey or surface, the user’s first success, the product mechanism or proof the interface may expose, evidence for visible claims, and constraints, prohibited claims, or unknowns. Backend-only work and product-level intents omit it, and the handoff does not choose engagement mode, visual direction, layout, motion, or implementation approach.

Optional independent shaping review

If the Core pack and its shaping-reviewer are installed, intent frame can send one attributed evidence packet to an isolated reviewer in intent mode. It is an optional augmentation: a genuinely fresh context or an independent human reviewing the same packet can stand in, while warm self-review is only advisory. The reviewer checks well-formedness, not quality: it returns one MALFORMED(<field>) token per failed condition, or nothing at all. intent frame retains the decision and status, and an unresolved token blocks a reviewed handoff.

Once the intent is well-formed, adversarial-reviewer in intent mode can attack the bet itself. It returns only an open question with a named decider or a validation hook — a kill condition plus the real-world activity that would trigger it — or nothing at all. That read is advisory: it settles no status, and intent de-risk still authors your kill condition.

Without Core or another independent route, the intent remains authorable. intent frame reports that the optional Core intent shaping review is unavailable and claims no review result.

2. De-risk the riskiest assumption

Invoke intent de-risk. It triages reversibility (one-way vs two-way door), picks the riskiest assumption, and — crucially — predeclares a kill condition in the test’s own currency (a number if you have traffic, a qualitative bar if you don’t) before running anything. It then runs under a prototype-approach:

• validate-first (default for irreversible bets) — build the cheapest probe that tests the kill condition, take the verdict.
• prototype-led (default for cheap, reversible bets) — build a prototype early and let it drive the intent’s refinement; the build is the test.

You get a survive/kill verdict. Killed → reframe. Survived → decompose.

3. Decompose to the smallest delivery contract

Invoke intent decompose. At app scale, one independently shippable feature routes directly to a core spec at docs/specs/<slug>/spec.md. Use a brief only when the intent coordinates multiple specs or crosses repository boundaries; the brief carries the shared outcome, success metrics, scope/non-goals, and appetite while the child specs own their delivery contracts.

4. Hand off to delivery

From here it’s the loop you already have: new-spec authors a direct single-feature contract, while author-delivery-brief continue decomposes a coordinating brief into specs. In both routes, work-loop builds the approved spec and the Contract: seam pins the detailed contract at spec authoring time.

---

Business-unit / cross-component. When a capability spans many component repos, intent decompose slices the feature intent per component into one brief per repo, coordinated from a value-stream meta-repo via align-value-stream. See the how-to Run a capability across a value stream.

What you have now

• A de-risked feature intent that records its outcome, opportunity, and assumptions.
• A route to new-spec for one independently shippable feature, or to a coordinating brief for multi-spec or cross-repository work.