Product Definition (the method)¶

This skill is the method. The theory lives in references/. Load a reference only when the stage you are in needs it. Never turn the output into a glossary; turn the theory into questions the product must answer with evidence.

Authority and placement (read first)¶

The current GTM document is the commercial authority, and it is not in the repos. Read the "2026 GTM" tab of "Bluefly Organizational GTM" (Google Doc 1ED288ChytgUrrTK301X1japW--b4cCj-rYjq5vHuydA) before defining anything, and re-check that it is still the newest tab. It states the product hierarchy every definition must fit: Digital Estate Operations is the recurring product, Migration Factory is the land motion, ContextControl is the customer control room, the Factory is the execution and margin engine, Drupal is the first market wedge. Summarized in references/bluefly-commercial-doctrine.md, which is a summary and not a substitute.
BLUEFLY_CONSTITUTION.md (Product > Factory > Outputs > Systems; compose, never reinvent).
BluCity-Docs (blueflyio/blu/blucity-docs) is the doctrine and portfolio authority for architecture and ownership: products/AUTHORITY-MATRIX.md, Engineering-Standard/authority/Portfolio-Registry.yaml, Engineering-Standard/glossary/platform-glossary.md, Playbooks/revenue-first-operating-playbook.md (Commercial Work Gate). Its commercial sections lag the GTM document; on commercial intent the GTM document wins and the lag is recorded as drift.
reference/corpus-reconciliation.md in this plugin lists where plugin text and corpus diverge. Where they conflict, follow the corpus for portfolio and architecture facts and flag the conflict in the definition's Open Questions.

Standing constraints that bind every definition: - No new projects, repos, modules, recipes, or templates. Curate what exists. A definition that requires a new repo must say which existing repo absorbs it or stop. - Products know Offerings; Offerings know Packs; Products never own a repository path. - Drupal is the customer product substrate and business authority, not the Bluefly control plane. - Prices, SLAs, guarantees, and compliance claims are DRAFT until operator approval. Label them. - One accountable owner per product. In the current estate that is the founder unless stated. - Chat transcripts, memory, and LLM output are L5 evidence. Never promote them without proof.

Inputs¶

Accept any of: a one-line idea; an existing products/<Product>/ directory; a repo or package; market research; a pack, formula, or module someone wants to sell; a customer conversation. Do not ask for a brief. Derive what evidence is missing and go get it (Stage 1).

Method¶

Run the stages in order. Each stage ends with a written finding in the definition file and an evidence grade (see Evidence Ladder below). A stage that cannot be graded above L5 becomes an Open Question, not a placeholder.

Stage 0. Kill the new product first (before anything else)¶

The skill's first job is preventing product sprawl. Try to kill the proposed product before defining it. Two failure directions, both caught here: - Sprawl: inventing a product an existing product already owns ("Drupal Agent Governance" is AMCS; "MemoryPlane" and "agent registry" are ContextControl capabilities). - Swallow: letting an existing product absorb the whole architecture (ContextControl becoming execution, work ledger, policy engine, telemetry, and vector store at once).

Answer with evidence from BluCity-Docs, the Portfolio Registry, and the GitLab estate: - Owner search first, and search where the commercial authority actually lives. Does an existing Product already own this outcome, buyer, or category? Search the current GTM document in Drive FIRST, then products/, Portfolio-Registry.yaml, blucity-packs, and the group. Repo-only searches have already produced two confident and wrong definitions (see references/worked-examples.md). If an owner exists, stop: the output is a definition of the OWNING product, and the proposal becomes an Offering, capability, or nothing inside it. - Fit the stated hierarchy or argue against it. Every proposal is a recurring product, a land motion, a control room, factory or substrate, or a market wedge. Adding a sixth slot is a leadership decision, not a definition. - Classify every named thing in the proposal with the classification enum in references/product-portfolio-taxonomy.md (COMMERCIAL_PRODUCT, COMMERCIAL_OFFER, CUSTOMER_CAPABILITY, BLUEFLY_COMPOSITION, INTERNAL_FACTORY_ASSET, UPSTREAM_PLATFORM, OPEN_STANDARD_OR_PROTOCOL, PROJECT_OR_REPOSITORY). Only COMMERCIAL_PRODUCT and COMMERCIAL_OFFER are sold. Everything else is removed from the sale and from the product name. - Is it a Company, Mountain, Product, Offering, Pack, Capability, Rig, Feature, Service, Standard, Protocol, Project, or Codename? Names create architecture assumptions. - Which Product, Factory, Output, Domain, and System would emit it? No answer means it is at the wrong layer and the definition stops here with a placement recommendation. - Draw the boundary against its nearest neighbors in one line each (for AMCS: ContextControl, Site Factory, Gas City; for ContextControl: AMCS, Gas City, Beads, Cedar, OtterMon). State which neighbor is a prerequisite and which is an expansion. A product that requires every neighbor to function has no boundary.

Stage 1. Problem and trigger¶

references/product-theory.md section Problem theory. Establish: who has the problem, frequency, pain, cost of the current workaround, vitamin or painkiller, budget already allocated or not, growing or shrinking, and the trigger event that makes someone go looking. No trigger, no buyer.

The catalyst must be dated and verified against its primary source, with the retrieval date recorded. Verify even when correcting an earlier figure: thresholds and deadlines move in both directions, and a confident correction sourced from the wrong project is worse than the stale number it replaces. When the primary source says the answer is undetermined, write that in its own words. Sequence multiple catalysts by date and let the nearest one organize the plan.

Stage 2. Customer¶

references/customer-psychology.md. Produce the ICP (industry, size, regulatory environment, technology, maturity, buying capacity, existing tools) and the persona map with distinct roles: user, champion, buyer, economic buyer, approver, blocker, administrator. Never collapse them into "the customer". State the four layers of motivation (functional, economic, emotional, identity) and what the customer actually purchases (thing vs outcome vs experience vs identity).

Stage 3. Market and competition (research)¶

references/market-research.md. Research the web and connected sources. Classify the market (existing, new category, replacement, niche, platform, vertical, horizontal). Analyze the four competitors: direct, indirect, internal build, do nothing. Record positioning, pricing, reviews, complaints, distribution, switching costs. Answer "why would someone choose us instead", not "what features do we have that they lack". Cite sources with dates.

Stage 4. Positioning, differentiation, value proposition¶

references/positioning-messaging-brand.md. One primary value proposition. Reject unevidenced differentiation words (innovative, AI-powered, seamless, enterprise-grade, next-generation). Positioning statement in the FOR / WHO / IS A / THAT / UNLIKE / IT form, treated as a tool. Bluefly positioning anchor: MCP connects agents to tools, A2A connects agents to agents, OSSA defines the agent, DUADP makes the agent discoverable, Bluefly sells governed modernization outcomes. Every product must sit inside that sentence or explain why not.

Stage 5. Product experience and factory mapping¶

Define core capabilities, the delivered experience, and an explicit "what this product is NOT". Where the product takes operational authority inside customer systems, define the authority ladder rather than a tier menu: Observe, Assist, Operate, with Operate earned per customer and per remediation class against verified history, policy and acceptance, and revoked automatically on regression (references/mvp-validation.md). Assist is the honest default for a long time; selling Operate as the starting point converts the top risk into the first failure. Then express it in Constitution terms: Product -> Factory -> Outputs -> Domains -> Systems, with each capability composed from an upstream. Custom code is listed only under custom_justifications with the named gap. If the product is a Factory SKU, produce or patch factories/<sku>/factory.yaml and run python3 scripts/factory.py check.

Stage 6. MVP, risks, evidence¶

references/mvp-validation.md. MVP is the smallest experiment that tests the riskiest hypothesis, not a small first version. Write the core hypothesis, the eight risks (market, product, technology, distribution, economic, adoption, trust, regulatory), the smallest test, and success criteria. Grade current evidence on the Product Evidence Ladder. Do not discuss scale before early adoption evidence exists.

Stage 7. Economics¶

references/pricing-economics.md. Business model (who pays whom, for what, when, why). Pricing basis and strategy. Cost of delivery including model and API usage, implementation labor, support, compliance, and hosting; for AI products COGS scales with success, so model it. Unit economics: revenue, COGS, gross margin, CAC, LTV, churn, payback, contribution margin. Do not apply generic SaaS benchmarks blindly. Mark every figure DRAFT pending operator approval.

Stage 8. Offer, GTM, sales motion¶

references/go-to-market.md and references/bluefly-commercial-doctrine.md. Offers sell products; write the offer (package, price, terms, guarantee, onboarding, risk reversal, proof). Place the product on the Service-to-Product ladder: expert capability -> paid engagement -> repeatable method -> productized service -> reusable assets -> recurring product. Choose the sales motion (founder-led, sales-assisted, PLG, partner-led, open-source-to-commercial) from evidence, not habit. Pick channels. Pass the Commercial Work Gate.

Stage 9. Brand, messaging, visual story¶

references/positioning-messaging-brand.md. Brand is the set of expectations attached to the product. Produce name check (taxonomy category), tagline, one-liner, elevator pitch, homepage headline and subheadline, three benefits with proof points, objection responses, CTA, the narrative arc (world today -> change -> why the old way fails -> new possibility -> product -> better future), and the one image that explains the product in ten seconds. For any visual asset apply the agentbrand and bluefly-design-system skills.

Stage 10. Adoption, retention, growth, moat¶

references/growth-retention.md. Name the activation event ("I get it" moment). Map acquisition -> signup -> onboarding -> activation -> habit -> retention -> expansion -> advocacy. State why the customer comes back, what gets better with use, what makes leaving costly, and what would make them cancel. Find product-driven distribution loops. Name the moat and be honest when features are the only one (that is not a moat).

Stage 11. Ownership, metrics, roadmap, kill criteria¶

references/product-ownership.md. One accountable owner. North Star metric plus acquisition, activation, engagement, retention, revenue, referral, cost, reliability. Lifecycle stage. Roadmap as outcomes and a betting sequence, not a feature list; keep vision, strategy, roadmap, backlog, and release plan distinct. Kill criteria with numbers and a date. Exploration is time-boxed with an exit decision: sell, validate with prospects, defer, or stop.

Stage 12. Open source and ecosystem (conditional)¶

references/open-source-products.md when any part is open. Define what is open, what is commercial, the monetization boundary, governance, contribution strategy, and what Bluefly owns versus what it enables others to build.

Output¶

Primary: one Product Definition in the shape of references/product-definition-template.md. Every section filled or moved to Open Questions. No placeholders, no "TBD".

Match the depth to the reader. A Product Definition is the working artifact; it is not the document leadership approves. Leadership approves a business strategy: the decision, the catalyst, the first sale, the conversion path, the economics, the limits on autonomy, what must be proven and by when. Policy-engine detail, schemas, configuration and architecture internals belong in technical appendices, and the leadership version is roughly half the length of the definition. When the reader is leadership, cut anything they cannot approve or veto.

Open with the Executive Decision table (PRODUCT_NAME, PRODUCT_TYPE, PRODUCT_FAMILY, PRODUCT_OWNER, ONE_SENTENCE_DEFINITION, COMMERCIAL_CATEGORY, CURRENT_MATURITY, PRIMARY DECISION). The primary decision is usually "X is the product; do not create Y" or "X is a capability of Z". Close with the Evidence State table: every load-bearing claim tagged CANONICAL_POLICY, CURRENT_PRODUCT_DIRECTION, CURRENT_SOURCE, HISTORICAL_SUPERSEDED, or NOT_ESTABLISHED (references/mvp-validation.md). "What is real now versus what remains unproven" is the most valuable section; never omit it. If that table has no row sourced from the current GTM document, the definition has not been checked against commercial authority and that absence is itself an Open Question. Worked calibration runs for AMCS and ContextControl are in references/worked-examples.md.

Derived artifacts (emit only those the stage evidence supports): positioning statement, pitch ladder (headline, one sentence, 30 seconds, 2 minutes), competitive analysis, MVP test plan, pricing sheet (DRAFT), offer sheet, GTM plan, roadmap, kill criteria, and where the product is a Factory SKU the factory.yaml patch.

Where it lands: - Doctrine goes to BluCity-Docs products/<Product>/ using the AUTHORITY-MATRIX filenames (Vision.md, Architecture.md, API.md or Spec.md, Deployment.md or Runtime.md, Roadmap.md). Instantiate a file only when its content is curated. Use the corpus frontmatter (bluefly_document: true, created_at, updated_at, status, owner, authority) and preserve the BLUEFLY-DOC-GOVERNANCE block. - Offerings and their pack bill of materials go to Portfolio-Registry.yaml offerings:. - Work goes to Beads. The definition is a projection, not the work. - Deliver through a branch and merge request against the remote. Never a local checkout only.

Evidence Ladder (grade every claim)¶

Lower confidence -> higher confidence: founder believes it; customer says it sounds useful; survey says people want it; user joins waiting list; user tries prototype; user repeatedly uses product; user pays; user renews; user expands; user recommends unprompted. Map to the corpus epistemic hierarchy: L1 runtime or cryptographic proof, L2 verified system state, L3 reviewed document, L4 stated intent, L5 unverified assertion or chat transcript. A definition built only on L4 and L5 is a hypothesis document and must say so in its first line.

Rules of thumb (enforce, do not recite)¶

Start with the problem, not the implementation. A user is not necessarily a buyer. A feature is not a product. Infrastructure is not automatically a product. "Everyone" is not a target audience. If everything is a priority there is no strategy. Payment is stronger evidence than enthusiasm. Distribution is part of the product. Brand reduces the cost of explanation. Price communicates positioning. Usage is not value unless it produces an outcome. Revenue without margin may be a liability. Growth without retention is leakage. An MVP tests uncertainty; it does not merely reduce scope. Do not automate what nobody wants. Do not scale before proving repeatability.

Failure modes this skill exists to stop¶

Grounding a definition only in the repos when the commercial authority is a document elsewhere. Asserting a dated catalyst without checking the primary source, including when "correcting" one. Claiming regulatory compliance that the mechanism cannot deliver: automated testing does not prove WCAG conformance, so sell detect, classify, remediate the programmatic classes, human review where required, verify, and never "AI makes your site compliant." Free pilots, which measure curiosity rather than demand. Publishing a price card before any customer has paid. Promising to replace tools the customer already owns instead of completing the loop they stop at. Writing a reusable artifact from a good idea rather than from accepted, repeated execution. Inventing a product an existing product already owns. Letting one product swallow the substrate. Selling the stack (modules, packs, protocols, runtimes) instead of the outcome. Pricing per agent when good orchestration reduces agent count. Every customer producing a fork (the product thesis fails when the next implementation is not cheaper than the last). Calling infrastructure a product. Calling a pack a product line. Renaming a directory and treating it as a new product (Site Factory -> Agent Factory). Publishing draft pricing as fact. Collapsing user, buyer, and blocker into "the customer". Writing a roadmap as a feature queue. Letting a sunk cost live without kill criteria. Building before the Commercial Work Gate is answered. Creating a new repo when an existing one should absorb the work.