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. frame-intent 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 frame-intent. 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 frame-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

frame-intent 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.

frame-intent 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.

Optional independent shaping review

If the Core pack and its shaping-reviewer are installed, frame-intent 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 returns Clean or Findings; frame-intent retains the decision and status, and unresolved findings block a reviewed handoff.

Without Core or another independent route, the intent remains authorable. frame-intent reports that the optional Core intent shaping review is unavailable and does not claim Clean.

2. De-risk the riskiest assumption

Invoke de-risk-intent. 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 decompose-intent. 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, decompose-intent 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.