phuryn/product-engineering / product/skills/propose
propose
Unverified'I have an idea', 'is this worth building', 'what next': research it and propose what to build, with sources and key screens to review. Not for agreed changes or bugs.
Propose — research an idea, then propose what to build
Research the idea, then propose what to build, interface first. The owner has an idea, or a product in use needs its next step. Read what the owner shared, find what is missing, set the idea against that evidence, and propose something the owner reviews.
Every claim is a hypothesis with a source until people use and pay. What comes out is informed hypotheses, never findings.
This is not an interview. Questions come last, and only the ones the evidence cannot decide. An interview sharpens what the owner already thinks; this brings in what the owner doesn't know yet.
Not for an agreed change, a bug or a small UI change. Those go straight to a plan or a build, as does anything the owner has already decided and asks to have built.
The owner decides; the agent owns the evidence. The owner owns the thesis, the segment, what gets built and when. The agent owns the evidence and the proposal artifact, and says plainly where the evidence and the owner's idea disagree.
Steps
1. Read what was shared, then what already exists
Read the owner's material and the product's existing record first. Read all supplied notes, research, data, links, screenshots and competitor names, then any brief, decision log and earlier proposal.
Use the repository's existing equivalent of a proposal. Duplicated proposals lose decisions between them. Rewrite an existing Markdown proposal once as HTML in the same place, removing the Markdown in that change while git keeps its history. On a rerun, start from the existing proposal (§ Running it again).
When the product implements a published method, write its steps before the use cases. Put those steps in the brief, above its use cases. Use the app-lifecycle skill's brief or the product's equivalent. Give each step a source, have the owner identify the authority and any simplification, then order the use cases accordingly. Check the first use case against the authoritative document as the first thing a new user does.
2. Research what is missing
- Research up to five alternatives the people in question actually use, including doing nothing. Include substitutes such as spreadsheets, agencies and manual workarounds, keeping them distinct from direct competitors. When installed, apply
competitor-analysiswith this narrower scope rather than its full report. Tell it to omit market-size, share and funding figures without sources. - Research an open segment and compare the value offered. Apply
market-segmentsandbeachhead-segmentwhile the segment remains open. Applyvalue-propositionandvalue-curvefor the proposition and curve against alternatives. - Gather what people say when the owner wants it. Use reviews, forums, Reddit and X for problems and people's words, without inferring prevalence or willingness to pay from those comments.
- Each quote is verbatim, checked against the page as fetched. Include its link and the date read.
- Leave out posts by a vendor, its staff or its affiliates. Also exclude paid or promoted posts. Keep only independent posts: astroturf reads as demand.
- Flag quotes fetched through mirrors or archives. Say when blocked fetching required that route.
- Every source gets its address and the date it was read. A claim without a source is your own.
Handle standalone market research here without building a proposal. For requests covering competitors, segments, a value proposition, a value curve or people's comments, follow this order without a proposal. Gather people's comments alongside under the same rules:
- The alternatives:
competitor-analysis. - The segments:
market-segments, thenbeachhead-segmentwhile the first one is open. - The value proposition for the chosen segment:
value-proposition. - The value curve against the alternatives:
value-curve.
Finish by marking every claim by kind (step 3); standalone research ends there.
3. Mark every claim by kind
If the proposal doesn't show each claim's source and mark the agent's own inferences, it is assumptions in a confident tone. For new products, most evidence is other people's words interpreted by a fluent model.
| Kind | Example | Used as |
|---|---|---|
| Observed fact or reported behaviour | a published price; a review saying "I export it to a spreadsheet every Friday" | evidence, with source and date |
| Owner constraint or preference | "I want to start with educators"; "no mobile app" | a decision: recorded, not argued with |
| Agent inference | "educators will pay, because they already pay for a similar tool" | marked as the agent's, with the evidence it rests on |
| Unsupported assumption | "teams will switch within a month" | named, and tested before anything rests on it |
- A competitor's marketing is evidence of how it positions itself. It does not establish capabilities or customer outcomes.
- The owner's preference is a decision; the owner's assertion is a hypothesis. "I want this segment" records a choice. "This segment will pay" remains a hypothesis sourced only to the owner; say so in the proposal.
4. Check feasibility before drawing screens
Check what may not exist or may not be allowed before drawing screens. Screens of something that can't be built waste the owner's review. Check the API, the platform rule, access to the data, or a cost per user that eats the price, and say what you checked.
5. Propose
- One direction when the evidence clearly favours it; two or three, with their trade-offs, when the choice is real. Inventing alternatives hides the recommendation.
- Show rough builder-hour size and lasting obligations beside every option. Label size as an estimate; lines of code can help when useful. Name what it adds to run: each service, store, job or vendor the product keeps. Put this beside directions and open decisions, so the owner sees the cost while choosing.
- Explain each direction's audience, value proposition, scope and advantage over alternatives. State what its first version does and deliberately leaves out.
- Weigh each part of the first version by what people will see against what it costs. Put visible, cheap parts early: a landing, displayed pricing and example data filling every screen. Add hard logic once the product is worth it.
- Name the weakest consequential assumption. Choose the one that, if wrong, changes the recommendation. A shaky detail that changes nothing can wait, even if it is the weakest overall.
- Recommend one direction and give the reason. Make the choice explicit in the artifact.
6. Build what the owner reviews, interface first
Build one self-contained HTML page with research, decisions and key screens. The page opens from its file without a server or build, with its sections in this order:
- Research, marking every claim by kind and source (§ 3).
- Alternatives.
- Segment.
- Value proposition and value curve.
- Recommendation (§ 5), with its impact-and-effort grid.
- Jobs map.
- Key screens.
- Open decisions.
- Hypotheses, including the weakest consequential assumption and its experiment.
-
Map jobs before drawing one high-fidelity screen per key job. Number each job in the user's words, naming its screen, the question that screen answers and its primary action. Each screen shows its job's number and realistic sample data labelled as such. When replacing a familiar tool, start from its structure and justify departures.
-
Apply the
ui-designskill. Read the method first, withapp-stackinstalled, or use the jobs map,frontend-designdirection, token values and a checked screenshot without it. Embed and compose an existing kit's CSS inside the HTML. For new products, choose one subject-grounded direction and keep values in tokens. Where the method is present, check screenshots against it before the owner sees them. -
Agree on static or clickable screens and build no separate prototype. The person and agent choose together. The first working version takes hours and tests the full flow.
-
Charts follow
dataviz's rules in any agent. In Claude Code, apply the built-indatavizskill (read2026-11-07). In any other agent, follow its rules:- The form first: sometimes a number, not a chart.
- One axis, and a legend for two or more series.
- Colour follows the entity; status colours only for status.
- Text in text colours, never a series colour.
- Look at the render.
Draw the value curve, segment scores and impact-and-effort grid. The grid weighs § 5's first-version parts and next builds by what people will see against cost. Mark "do first".
-
Fresh eyes before the owner: a fresh session reads the page first. It gets only the page's screenshots (a tall page cut into ordered parts) and a reader's role, never the brief or the code. Ask what the page is, what the reader would decide from it and what is unclear, then fix what they cannot explain. This checks the page itself: no app crawl or sign-in.
-
Name key screens and what to inspect before any plan. Give the owner that preview.
-
Define the customer experiment and what would change the recommendation. Include hypothesis ID, participants, task, observed behaviour and the decisive result. Building the first version and putting it before paying users is often the experiment.
7. Ask only what the evidence can't decide
Keep questions in the artifact and record every answer durably. Ask only the few questions evidence cannot decide, about the owner's values, segment or scope. Put each in open decisions with options, a recommendation and its reason. Each option shows its rough builder-hour estimate and what it adds to run (§ 5).
Support both saved page picks and choices copied into chat. Where the host saves viewer picks, let the person pick on the page and read those picks next iteration. Claude.ai artifacts can save picks (read 2026-11-07). For local files and other hosts without saved picks, provide a button copying choices as text for chat; direct chat answers also work. The same file supports both paths.
Write each pick into HTML and the decision log immediately. Do this in the same turn whichever way it arrives, then republish. Host-only page storage loses choices to the next session and other agents.
Ask these questions only here and keep decisions with the owner. If work has an owner's page, apply flight-deck and link from that page to the questions. (The author's preference, as an example to replace with your own: "a person talking to Claude", 2026-11-07.) The owner may share the page like any other; the decisions remain theirs.
8. Write the record
Keep the HTML file as the one durable proposal record. Use the repository's existing location, else docs/product/proposal.html, and read references/proposal.md for its sections, keeping key screens inside the record. Create no Markdown duplicate; restating the record elsewhere loses decisions.
Publish from the HTML file and republish it each iteration. Where the host publishes pages, keep the published page aligned with this file; in Claude, publish a claude.ai artifact (observed 2026-11-07).
| Record | Holds |
|---|---|
| The proposal artifact | research with claim kinds and sources, alternatives, segment, value proposition and curve, jobs, screens, decisions, hypotheses and experiments |
| The brief (or the product's refined idea) | the accepted intent and use cases |
| The decision log, if there is one | the choices made, their reasons, what would reopen them |
After the owner accepts, update the brief and link the page as evidence. Update the decision log where needed too. Write no second brief when the accepted proposal already does that job. For a SaaS, apply the app-lifecycle skill with the accepted artifact.
Plan complex changes next, opening with assumptions the owner must review. After acceptance, the next step for a complex change in any product is a plan. Explain what the ask means in this product, any wrong number or word the owner supplied, and what needs their decision.
Put visible changes and open choices on the review page. Use this page or a new one in the same form, showing key assumptions, high-fidelity screens of changed flows, then choices picked as § 7 describes. Keep the builders' part in the repository's plan: phases, files each changes, tests and acceptance criteria. Name tests touching production, its users or its data; run them only with the owner's go.
Running it again, once people have used it
Rerun the proposal using what real users did and paid for. Collect what they used, returned to and abandoned, and record its origin: analytics, payments, support or interviews.
- Update and republish the same HTML file. Append evidence, update conclusions, and place each dated observation under the hypothesis it bears on, by ID. Update each hypothesis's status: supported, weakened, refuted or untested. Replace the recommendation; keeping old and new together leaves the builder choosing between them.
- What people say they did counts; what they say they would do is a hypothesis again. Test what people say they would do.
Each rule's origin, the case that taught it, is in receipts.md beside this file; read it when a rule's edge is unclear.
How you can tell it worked
The owner can trace every claim, saw key screens before planning, made decisions on the page or in chat, and answered only questions requiring their judgement. They know which hypothesis the first users will test and what result changes the plan.
Files
| File | Holds | Read when |
|---|---|---|
references/proposal.md | the proposal's sections, the hypothesis table and the observation log, as HTML page sections | writing or updating the record |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 114k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 114k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 114k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 114k | Updated | Claude CodeCodex | Verified | Install |