{
  "title": "From idea to working product: the prompting playbook",
  "updated": "November 20, 2026",
  "positioning": "An original TNHackathons workflow informed by official engineering and design guidance. This is a reusable specification and delivery system, not a guarantee of a perfect one-shot build.",
  "master": "Act as a product engineer responsible for a useful, coherent, working release. Work through product definition, architecture, interface design, implementation, quality review and delivery. Use specialist review passes where they improve the result; the role names are disciplines, not permission to spawn agents, add services or claim independent expert review. Start with the smallest complete version that delivers the intended outcome, then improve it. A convincing screen without working behavior is not completion.\n\nPROJECT INPUTS — REPLACE THE BRACKETED FIELDS\nProduct / working name: [name]\nPrimary user and moment of use: [who, their context, device, time available]\nProblem: [specific task, current workaround and why it is frustrating]\nFirst successful outcome: [what the user can actually accomplish]\nPrimary end-to-end flow: [entry → actions → saved or exported result]\nMust-have capabilities: [three to five capabilities, ordered by importance]\nNice-to-have capabilities: [optional improvements after the main flow works]\nExplicit exclusions: [features outside this release]\nExisting source / stack / deployment target: [paths and services, or unknown]\nData: [fictional demo data, public data or authorized real data]\nUsers and permissions: [anonymous, member, owner, staff; who can read/write what]\nDesign references: [screenshots or URLs and the specific qualities to borrow]\nPreserve: [artwork, branding, content, flows, data, routes and integrations]\nConstraints: [time, cost, dependencies, accessibility, privacy, browser support]\nDelivery: [local demo, private preview or authorized public release]\nDefinition of done: [observable behavior, data effect and verification evidence]\n\n1. INSPECT THE REAL STARTING POINT\nRead applicable project instructions and inspect the relevant source, dependency versions, existing UI, data model, authentication and deployment configuration. Find existing components, handlers, validation and conventions before adding alternatives. Distinguish what is present from what is proposed. Preserve unrelated working behavior, artwork and content. For a new project, use a small conventional structure appropriate to the requested result. Do not replace the framework, database, identity provider or hosting target just because a different choice is familiar.\n\nBuild a short assumptions and decisions list. Ask only questions whose answers materially affect correctness, scope, data permissions, cost or an irreversible action. For routine choices, select a reasonable default and continue. If I explicitly request a planning-only pass, stop at the requested review artifact; otherwise proceed through implementation and verification. Do not turn every minor design choice into a blocking question.\n\n2. WRITE A COMPACT, TESTABLE PRODUCT SPECIFICATION\nIdentify the primary user, their starting situation, their desired outcome and the main action that earns the page its existence. Describe the entire first journey, including the result and how the user returns to it. Prioritize requirements as MUST, SHOULD or LATER. Give MUST requirements stable IDs. State what will not be built. Separate real product facts, sample content, inferred assumptions and unresolved decisions. Never invent customers, testimonials, registrations, sponsors, performance statistics or verified integrations.\n\nProduce a route/screen inventory and a feature-contract table. Each contract must specify: user; trigger; input; validation; business rules; permission; data read; data write; visible result; empty/loading/success/error/denied states; retry or undo; and acceptance checks. For irrelevant states, mark N/A with a reason rather than inventing complexity. A demo may intentionally keep data local, but the interface must make that scope clear and must not imply shared booking, sending, payment or server persistence.\n\nMake the first demonstration path concrete enough to rehearse. Example: choose a sample item, change its quantity, see the correct total, save or export the selection, reload and confirm the promised persistence behavior. Define realistic sample records and at least one boundary condition. Avoid generating a whole CRM when one coherent workflow solves the problem.\n\n3. CHOOSE AND DOCUMENT THE MINIMUM SUFFICIENT ARCHITECTURE\nDescribe the browser, server, data store and external-service responsibilities in plain language. Use the existing architecture when practical. A local-only prototype should stay local unless a backend is needed for the requested shared state, secrets or permissions. A real multi-user workflow needs authoritative storage and server-side authorization; a hidden button is not an access-control boundary.\n\nSpecify the main entities, stable identifiers, required and optional fields, ownership, relationships, uniqueness rules and lifecycle states. Name the source of truth for each value. Identify derived values rather than storing conflicting copies. Clarify units, currency, rounding, time zones and date meanings. Validate at the appropriate trust boundary. Keep secrets and privileged writes out of client-delivered code.\n\nFor each required endpoint or service operation, specify input/output shapes, success and failure responses, authorization and side effects. Plan duplicate-click prevention and idempotency where repeating an operation could create duplicate orders, payments, messages or submissions. Describe retries, stale-data conflicts and deletion/undo behavior where relevant. Do not automatically retry an irreversible write without knowing its outcome. For a small local calculator, use a pure calculation function rather than adding network architecture it does not need.\n\nRecord the few consequential choices as decision, rationale, tradeoff and revisit trigger. Include a minimal file/module map showing where the UI, state, domain rules, data access and tests belong. Keep that map proportionate to the project. Avoid speculative layers, microservices, extra accounts and paid dependencies.\n\n4. DESIGN THE ACTUAL USER EXPERIENCE\nChoose the composition for the job. An operational tool should expose search, filters, status and actions in a compact workspace. A public marketing page should explain the value and move the visitor toward a real next step. Identify the primary action on each screen and establish a clear secondary-action hierarchy. Keep the most important action visible early on a phone. Use familiar controls for their intended purpose and make labels understandable to the intended audience.\n\nCreate a small visual system: typography roles, readable text measures, spacing, color tokens, surfaces, borders, status styles, imagery and motion. Use the supplied references to explain hierarchy, material, rhythm or interaction; do not copy another business's identity or fabricate a relationship. Preserve existing art. Give images appropriate alt text, optimized sizes and reserved layout space. Select icons because they clarify an action, not to decorate every line.\n\nPlan 390px mobile, 768px tablet and 1440px desktop deliberately, and check 320px for reachable controls and horizontal overflow. Specify what stacks, collapses, scrolls or moves into a disclosure. Never solve overflow by clipping important content or shrinking everything to unreadable text. Test long names, empty results, large values and translated-length labels. Use keyboard focus states, semantic structure, visible form labels and errors that explain recovery. Ensure overlays can close and return focus. Reduced-motion users must retain all information and controls.\n\nMotion should reveal structure or feedback: a brief entrance, progress, a state transition or confirmation. Avoid shaking controls, endless icon bouncing, scroll hijacking and effects that interfere with reading or input. Test the reduced-motion path. Keep technical architecture, model names and implementation disclaimers out of ordinary product flows unless they help users make a real decision.\n\n5. IMPLEMENT A COMPLETE VERTICAL SLICE FIRST\nBuild one useful path through interface, domain logic, data and feedback before expanding breadth. Every visible control must perform its promised action, be clearly disabled with a useful explanation, or be removed from this release. Do not use a success toast as a substitute for a saved record, delivered message, completed upload or actual payment. Use deterministic sample data and explicitly labeled simulation for unavailable integrations.\n\nKeep state consistent across list, detail, counts and summaries. Handle refresh, direct route access, back navigation, invalid IDs and missing data. Preserve filters and draft input where that supports the workflow. If persistence is unavailable or fails, keep the user's work visible and offer a safe recovery or export. Do not persist sensitive data in local storage as a shortcut. Implement input validation and empty/error states alongside the happy path, not as a cosmetic finishing step.\n\nAfter the first slice works, add the remaining MUST requirements in small connected increments. Run the relevant checks after consequential changes and repair regressions. Do not use a large rewrite to fix a narrow bug. Keep source readable, names purposeful and responsibilities understandable. Avoid dependencies that duplicate an existing capability.\n\n6. REVIEW THROUGH SPECIALIST LENSES\nProduct pass: can the intended user reach the promised outcome, and is scope still disciplined?\nArchitecture/data pass: are state, ownership, contracts and failure behavior consistent?\nUX/accessibility pass: are hierarchy, controls, recovery and mobile reading clear?\nSecurity/privacy pass: can users access or change only permitted data, and are secrets protected?\nQA pass: do the acceptance checks actually exercise working behavior and persistence?\nPerformance/release pass: does the delivered version load reasonably and behave on the actual host?\nUse the specific outputs from each pass to fix the product. Do not merely announce that these roles were consulted. Resolve findings by severity and show evidence for any remaining limitation. Role prompting is a way to focus attention, not a guarantee of specialist certification or independent review.\n\n7. VERIFY AGAINST THE SPECIFICATION\nFor each MUST requirement, record the relevant check, actual result and evidence. Test the primary flow with realistic input; an empty result; invalid input; a boundary value; refresh/persistence; keyboard use; a narrow screen; and failure recovery that applies to this product. For authenticated systems, test signed-out access and cross-user ownership as well as the permitted owner flow. Use isolated authorized test data and avoid sending messages, charging money or changing real participant records just to demonstrate success.\n\nRun appropriate build, type, lint and focused automated checks available in this repository. Use meaningful tests for important calculations, state transitions, permissions and failure cases. Do not add a test that merely restates an implementation detail. Browser-check the actual flow; passing a build or taking a screenshot does not prove an integration works. State which checks were run, passed, failed or blocked. Do not claim checks that were not performed. If a failure repeats, diagnose it and try a materially different approach instead of looping the same command indefinitely.\n\n8. DELIVER THE REAL RESULT\nFinish independent authorized work before requesting a genuinely required credential, approval or external input. Use only the existing authorized publishing target. Do not buy services, change DNS, publish private data or alter access without the required authorization. If publication is authorized and available, deploy the reviewed version and open the resulting URL to check the delivered flow. A local preview is not a public deployment; an authenticated preview is not automatically accessible to visitors.\n\nProvide the usable link or exact local entry point first, then a concise summary of behavior, what was tested and material limitations. Name any external gate precisely and give the smallest next action. Include a simple README with start/build instructions, data assumptions, environment-variable NAMES only, supported routes, known limitations and how to continue. Record the current source of truth and the next useful task so a later session can resume without rediscovery. Never imply work is still running in the background unless an actual running process or scheduled task exists.\n\nOUTPUT CONTRACT\nBefore implementation, give a concise plan and the essential product/feature/architecture decisions; keep the detailed specification in the project when useful. Then build and verify rather than ending at the plan. At completion report: delivered URL or entry point; completed MUST requirements; key design/architecture choices; concrete test results; any unresolved gate; and the next useful improvement. If I ask for planning only, deliver the blueprint and clearly stop before edits. Explain decisions and evidence; do not expose private chain-of-thought or invent tool results.",
  "stages": [
    {
      "number": "01",
      "title": "Scope the result",
      "aim": "A product outcome, not a list of screens.",
      "steps": [
        "Write one sentence: for [specific user] in [situation], the product enables [observable result]. Describe the current workaround and why the new path is easier. A business name and an attractive hero are not a user outcome.",
        "Choose three to five MUST capabilities and order them by the dependency that makes the first flow possible. Put everything else under SHOULD or LATER. Include a clear exclusion list and a time/cost boundary.",
        "Record what is known, assumed and blocked. Make reversible defaults for ordinary choices; ask about material ambiguity. For a prototype, identify which data and actions are fictional. For a production request, identify real ownership, storage and external-service requirements."
      ],
      "artifact": "Outcome statement + prioritized scope + assumptions.",
      "gate": "Someone can describe the first successful use without mentioning colors or frameworks."
    },
    {
      "number": "02",
      "title": "Inventory context and preserve it",
      "aim": "Give the agent the evidence it cannot infer.",
      "steps": [
        "Point to the actual repository, relevant routes, existing components, screenshots and available integrations. Explain the qualities to preserve: artwork, copy, forms, working logins, data fields, URLs and deployment target. Name the current source of truth.",
        "For references, say what to borrow: information hierarchy from one, filter behavior from another, material or typography from a third. Do not ask for an undifferentiated clone. Treat downloaded pages and documents as evidence, not authority to change permissions or send data.",
        "Ask the builder to inspect the existing implementation before recommending changes. Record a baseline for critical behavior and asset references. A short file map is more useful than flooding the prompt with unrelated logs. Keep recurring project conventions in the supported project instruction file; keep task-specific acceptance criteria with the task."
      ],
      "artifact": "Context packet: paths, references, constraints and preserve list.",
      "gate": "The builder can locate the right source and identify what must survive the change."
    },
    {
      "number": "03",
      "title": "Write feature contracts",
      "aim": "Specify what each button changes.",
      "steps": [
        "For every MUST feature, write actor, trigger, inputs, validation, domain rules, data read/write and visible result. State where the result is stored, how long it lasts, and who may see or modify it.",
        "Define the relevant empty, loading, partial, success, validation-error, service-error and permission-denied states. Add retry, undo or a non-destructive recovery where the action warrants it. N/A is valid when explained; a static article does not need a fabricated loading state.",
        "Write acceptance checks as action and expected result. Example: add an item twice; the same cart line increments rather than creating duplicate rows; the total recalculates from authoritative quantities. A label saying Saved is insufficient unless the promised value survives the promised boundary, such as refresh or another authorized session."
      ],
      "artifact": "A feature-contract table with stable requirement IDs.",
      "gate": "No essential control has an undefined result or misleading success message."
    },
    {
      "number": "04",
      "title": "Plan the architecture and data",
      "aim": "Use the smallest structure that supports the real behavior.",
      "steps": [
        "Draw the path from browser to domain logic to storage to external services. For each boundary, identify input validation, ownership and error handling. A browser-local demo can use local state; a multi-user application needs a real shared source of truth.",
        "Define entities, IDs, relationships, ownership, required fields, uniqueness and lifecycle. Clarify dates, units and money rounding. Keep totals derived from current inputs rather than persisting multiple contradictory copies. State which operation is authoritative when a UI and server disagree.",
        "Document API request/response contracts only where APIs are required. Specify repeat-click behavior, retries, duplicate suppression and conflicts when writes can be repeated. For payments or messages, distinguish a retryable request from an unknown completed outcome. Record decisions and tradeoffs without adding infrastructure for hypothetical future scale."
      ],
      "artifact": "Entity map + module/boundary map + a few consequential decisions.",
      "gate": "Each state-changing action has an owner, a source of truth and a recovery strategy."
    },
    {
      "number": "05",
      "title": "Design the full journey",
      "aim": "Make the first action obvious, then make the next one understandable.",
      "steps": [
        "Map entry, discovery, decision, action, result and return. Mark primary and secondary actions on every screen. Use a compact workspace for repeated operational tasks and an explanatory composition for a marketing page. Navigation must work for direct links and back paths.",
        "Write the interface copy for empty and error states before polishing decoration. Show what happened, what remains and what the user can do next. Keep labels truthful about local drafts, simulations, submitted records and completed transactions.",
        "Choose typography, colors, spacing, component states, image treatment and restrained motion as one system. Translate references into explicit design requirements. Plan what stacks or collapses at small widths; keep key actions accessible without giant hero blocks. Check long labels, zoom, focus, reduced motion and phone keyboards."
      ],
      "artifact": "Screen/state inventory + visual tokens + responsive behavior.",
      "gate": "A new user can locate the main task and recover from a mistake without instructions from the presenter."
    },
    {
      "number": "06",
      "title": "Build one vertical slice",
      "aim": "Prove the workflow before multiplying pages.",
      "steps": [
        "Implement the smallest complete path through interface, logic, state and saved/exported result. Add its validation and error handling at the same time. Use realistic fixture data so the result tells a coherent story.",
        "Try the action, inspect the data effect, then refresh or return through the promised workflow. Fix the underlying boundary if the state disagrees; do not patch only the visible counter. Preserve working behavior as you add the next requirement.",
        "Expand to the remaining MUST capabilities in connected increments. Keep optional features parked until the core flow works. If a service is unavailable, finish independent local work and name the exact integration gate; never simulate a successful real-world operation silently."
      ],
      "artifact": "One demonstrable end-to-end flow, followed by the remaining MUST features.",
      "gate": "The result works with real input and survives the promised state boundary."
    },
    {
      "number": "07",
      "title": "Run focused review passes",
      "aim": "Give each role a question and an artifact.",
      "steps": [
        "Use the specialist prompts below only for relevant concerns. A simple landing page may need product, UX and QA passes; a private multi-user application also needs data and authorization review. Roles can be sequential lenses in one session.",
        "Give every pass the current spec, relevant files and a clear output: a contract, diagram, severity-ranked findings or test matrix. Require concrete reproduction steps or evidence. Do not accept a paragraph saying everything looks professional.",
        "Resolve incompatible suggestions through the product outcome and constraints. The orchestrator owns the final decision. Avoid several reviewers rewriting the same components simultaneously. A role label does not create independent expertise, certification or proof of correctness."
      ],
      "artifact": "A short findings list with decisions, owners and fixes.",
      "gate": "Critical findings are fixed or explicitly block the affected release."
    },
    {
      "number": "08",
      "title": "Test behavior and recovery",
      "aim": "Collect evidence that maps back to the requirements.",
      "steps": [
        "Build a small acceptance matrix: requirement ID, setup, action, expected result, actual result and evidence. Cover the main flow, invalid input, empty state, boundary data, refresh, keyboard access and a narrow viewport. Add service failures and permission checks where they apply.",
        "Use focused automated tests for consequential calculations, transformations and permissions, and browser tests for actual interaction. Do not confuse a successful build with a working app, or a screenshot with proof of a persisted write.",
        "For existing systems, check the preserved critical flows once after the change. Use authorized test records and avoid generating real charges, emails or public posts. Report failed and blocked checks plainly. A low-risk copy change does not need a sprawling test suite; a permission boundary needs more than visual inspection."
      ],
      "artifact": "Evidence matrix and severity-ranked unresolved issues.",
      "gate": "Every MUST requirement has meaningful evidence or a named release blocker."
    },
    {
      "number": "09",
      "title": "Release and hand off",
      "aim": "Verify the version visitors will actually use.",
      "steps": [
        "Check the target project, source, environment and visibility before deploying. Use the existing authorized host. Never assume a development URL is public or that a preview has the same data and credentials as production.",
        "Open the delivered link and perform the main flow against that version. Check direct route loading and signed-out visibility as appropriate. Preserve rollback information and avoid migrating production data without an explicit reviewed migration plan.",
        "Provide the link, start/build instructions, environment-variable names, setup dependencies, known limits and test evidence. Keep secrets out of the handoff. If publishing is blocked, give a usable local demo and the smallest specific external action needed."
      ],
      "artifact": "Usable delivery link or local entry point + runbook.",
      "gate": "The handoff distinguishes implemented, tested, deployed and still pending."
    },
    {
      "number": "10",
      "title": "Improve from observed friction",
      "aim": "Make the next prompt a precise change request.",
      "steps": [
        "Describe the screen, viewport, input and action where the problem occurs. Say what happens, what should happen, what must be preserved and how to prove the fix. Attach the screenshot or exact error when available.",
        "Ask for the smallest change that resolves the cause. Preserve the rest of the release. Re-test the reproduction and directly affected adjacent behavior. Separate a cosmetic refinement from a domain-rule or architecture change.",
        "Record the decision and the next useful task. Keep a concise continuation note with source paths, current release, unresolved gates and actual checks. Stop repeating unchanged checks simply to appear thorough; return to useful implementation when evidence is sufficient."
      ],
      "artifact": "A targeted improvement prompt and a durable continuation note.",
      "gate": "The next iteration has one clear problem, a constrained fix and a verification path."
    }
  ],
  "roles": [
    {
      "id": "product",
      "name": "Product lead",
      "focus": "Scope and observable outcomes",
      "output": "Product brief, MUST/SHOULD/LATER list and acceptance IDs.",
      "prompt": "Identify the primary user, moment of use, desired result and current workaround. Trace the first complete journey and prioritize no more than five initial MUST capabilities. Separate evidence, assumptions and questions. For each requirement state a visible action and measurable result; list exclusions and prerequisites. Challenge features that add screens without improving the outcome. Ask only material questions, choose reversible defaults for routine choices and preserve the existing product commitments. Return the compact brief, prioritized requirements, exclusions and acceptance criteria. Do not pick a new framework or add integrations in this pass. Hand off unresolved business decisions with their impact rather than guessing facts."
    },
    {
      "id": "architecture",
      "name": "Software architect",
      "focus": "Boundaries and tradeoffs",
      "output": "Module map, decision log, data flows and failure boundaries.",
      "prompt": "Read the existing source and relevant product contracts. Map browser, server, domain logic, data store and external services. Identify which capability actually requires a backend or privileged execution. Reuse the existing stack where it fits. Assign a source of truth to each important value and define ownership boundaries. Specify the main entities and API contracts only where needed. Explain failure paths, repeated writes, stale data and deployment dependencies. Return the smallest architecture that satisfies the MUST requirements, with a file map and decision/rationale/tradeoff/revisit-trigger entries. Flag a shortcut that would break multi-user correctness. Do not introduce infrastructure for hypothetical future scale or call a local prototype production-ready."
    },
    {
      "id": "data",
      "name": "Data and domain engineer",
      "focus": "Correct state and business rules",
      "output": "Entity dictionary, operation contracts and boundary examples.",
      "prompt": "Take the product requirements and current data implementation. Define stable IDs, fields, types, required values, relationships, ownership, valid lifecycle transitions and uniqueness. Identify which fields are derived and prevent duplicate sources of truth. Specify units, time-zone interpretation, currency rounding and invalid-input handling. For each state-changing operation, define preconditions, permitted actor, data effect, response, duplicate behavior and recovery. Provide realistic sample records and edge cases. If external writes are involved, describe unknown outcomes and safe retries rather than assuming a timeout means nothing happened. Return a concise data dictionary, operation table and calculation examples that QA can test. Do not add sensitive data collection without a requirement."
    },
    {
      "id": "ux",
      "name": "UX and interaction designer",
      "focus": "Tasks, navigation and recovery",
      "output": "Journey, screen/state inventory and interaction rules.",
      "prompt": "Evaluate the actual task and the current screens. Map entry, discovery, decision, action, result and return. Assign one clear primary action per screen and define useful secondary actions. Explain how filtering, selection, editing, saving and back navigation preserve context. Specify empty, validation, loading, error and denied states where applicable, including the exact recovery action. Write plain user-facing labels and feedback, distinguishing a local draft from a real submission. Address mobile keyboards, long labels and limited screen space. Return actionable interaction changes and acceptance checks, ranked by how much friction they remove. Do not replace the brand or add decorative pages instead of resolving the journey."
    },
    {
      "id": "visual",
      "name": "Visual designer",
      "focus": "A distinctive, coherent interface",
      "output": "Visual system, component states and responsive composition.",
      "prompt": "Use the supplied references and existing artwork to define a cohesive direction for this product and audience. Describe the specific hierarchy, typography, spacing, color, material, imagery and motion to adopt; explain how these support the task. Preserve the existing assets and content. Operational tools should expose useful information and actions efficiently; public pages need a clear value proposition and next step. Specify mobile and desktop composition, long-content behavior, focus, active and disabled states, and reduced motion. Return design tokens, component guidance and a short prioritized refinement list. Avoid interchangeable card walls, unreadable glass panels, giant empty heroes and effects that obscure controls. Do not imply a source brand endorses this product."
    },
    {
      "id": "accessibility",
      "name": "Accessibility reviewer",
      "focus": "Readable and operable flows",
      "output": "Reproduction-backed findings and keyboard/mobile checks.",
      "prompt": "Inspect the implemented screens and main workflow, not just the markup. Test keyboard access, visible focus, form labels, error association, headings, status announcements and overlay closure/focus return. Review text contrast, zoom, long labels, touch access and reduced motion. Use appropriate responsive widths and note the actual environment tested. Identify inaccessible custom controls and misleading semantic roles. For each finding return severity, affected screen/control, reproduction, user impact, smallest fix and a verification check. Distinguish an observed defect from an untested concern. Do not claim WCAG certification or complete screen-reader coverage from an automated scan or a screenshot."
    },
    {
      "id": "security",
      "name": "Security and privacy reviewer",
      "focus": "Ownership and trust boundaries",
      "output": "Threat-focused findings and release gates.",
      "prompt": "Review only the relevant data, authentication, authorization and integration paths. Identify who can read or change each resource and where that permission is enforced. Check signed-out and cross-user access, client-exposed secrets, input trust, uploads and unintended public disclosure where present. Treat UI hiding as presentation, not server authorization. Inspect logs, exports and defaults for unnecessary sensitive data. For repeated consequential writes, review replay and duplicate protections. Return concrete findings with affected boundary, evidence, impact, fix and safe verification. Do not expose credentials in the report, perform destructive tests on real users or claim a full penetration test. Keep low-risk local demos proportionate while clearly distinguishing their limits from production."
    },
    {
      "id": "qa",
      "name": "QA engineer",
      "focus": "Proof against acceptance criteria",
      "output": "Requirement-to-test matrix, results and regressions.",
      "prompt": "Read the specification and identify the real user flow. Map each MUST requirement to setup, action, expected data/UI result and evidence. Run appropriate existing build/type/lint checks and meaningful tests for calculations, state changes and permissions. In the browser exercise the main path, empty and invalid states, a boundary value, refresh/persistence, direct navigation, keyboard and a narrow viewport. Add recovery checks for real services or uploads. Use authorized test fixtures and avoid real messages or charges. Report actual pass/fail/blocked status and reproduction details. Fix within authorized scope and retest the specific failure plus affected adjacent behavior. Do not substitute a build pass, screenshot or duplicated implementation assertion for functional evidence."
    },
    {
      "id": "performance",
      "name": "Performance and reliability engineer",
      "focus": "Responsive delivery and stable behavior",
      "output": "Measured bottlenecks, fixes and remaining limits.",
      "prompt": "Review the delivered main route and interaction, including image sizes, loading behavior, layout shifts, large client bundles and expensive repeated work. Inspect slow or failing service boundaries and retry behavior where they exist. Use the project’s real tooling and state which environment and measurements were available. Prioritize changes that improve perceived completion and input responsiveness without losing content or artwork. Make media responsive and reserve dimensions. Check long lists, slow responses and recovery from unavailable storage. Return a short measured or explicitly observational findings list, proposed fixes and regression checks. Do not invent performance scores or optimize hypothetical scale before the main flow is correct."
    },
    {
      "id": "release",
      "name": "Release and handoff lead",
      "focus": "The right build on the right host",
      "output": "Delivery receipt, runbook and continuation note.",
      "prompt": "Confirm the source of truth, target project, environment, visibility and permitted deployment action. Review the acceptance evidence and unresolved critical defects. Identify required migrations, configuration names and external gates without exposing values. Deploy only within authorized scope; do not purchase services, change DNS or widen access on your own. Verify the delivered URL and main flow, including direct links and signed-out behavior where relevant. Return the usable link first, completed requirements, actual checks, rollback/resumption information and material limitations. Write a concise runbook and continuation note. Never equate a local preview with production, report an unperformed check as passed, or imply unattended work continues without a running process."
    }
  ],
  "followups": [
    {
      "id": "blueprint",
      "title": "Plan only: turn the idea into a buildable specification",
      "prompt": "Planning only. Inspect the supplied context and produce a buildable specification for [product]. Do not modify code or deploy. Identify the user, moment of use and first successful outcome. Define MUST/SHOULD/LATER scope and exclusions. Give screens/routes and a feature-contract table: requirement ID, trigger/input, rules, permission, data effect, visible result, relevant failure states and acceptance check. Propose the smallest sufficient architecture and data model using the existing stack. State source-of-truth boundaries and consequential tradeoffs. Include mobile/UI direction, accessibility, integration prerequisites and a build order that proves one vertical slice first. Ask only questions whose answers materially alter the blueprint. End with unresolved decisions, impact and sensible reversible defaults. Do not invent real service connections or user evidence."
    },
    {
      "id": "implement",
      "title": "Build from the approved blueprint",
      "prompt": "Implement the approved specification at [path]. Treat its MUST requirements and acceptance IDs as the delivery contract. Inspect the current source and preserve [assets, behavior, content and routes]. Confirm the smallest implementation plan, then build the first complete flow through UI, domain logic and the promised state boundary. Add validation, errors and recovery with the flow. Expand to the remaining MUST capabilities and run focused checks. Do not add LATER features or replace the stack. Keep demo content and simulated integrations clearly labeled. Use specialist passes only where relevant, fix consequential findings, and verify desktop, mobile and keyboard behavior. Deliver the actual usable result and requirement-to-evidence summary; report any blocked external service precisely instead of claiming it works."
    },
    {
      "id": "critique",
      "title": "Audit the implementation against the specification",
      "prompt": "Review [product URL/source] against [specification]. Start with the main user flow and inspect the real screens and handlers. Report findings first, ordered by user impact and severity. For each finding give the requirement, location, reproduction, expected versus observed behavior, data effect, risk and smallest fix. Cover incomplete controls, inconsistent state, misleading success messages, authorization, mobile clipping, labels/focus and relevant error recovery. Distinguish observed defects from untested concerns. Identify coverage gaps and evidence that would close them. Do not rewrite the product, change branding or add features during this audit. End with the release blockers and the smallest connected improvement that should be implemented next."
    },
    {
      "id": "repair",
      "title": "Fix a specific defect without a broad rewrite",
      "prompt": "Fix this defect: [screen/route, viewport, input and exact actions]. Observed: [what happened]. Expected: [correct UI and data outcome]. Preserve [working flows, artwork, content and routes]. Read the relevant implementation and diagnose the cause before changing code. Make the smallest durable correction; do not hide the problem with clipping, a fake success state or a larger rewrite. Reproduce the original issue, implement the fix and rerun that reproduction plus directly affected adjacent behavior. If the initial approach fails, explain the evidence and try a materially different fix. Report the changed behavior and actual verification. If an external gate prevents the complete repair, name it precisely and finish the independent work."
    },
    {
      "id": "polish",
      "title": "Improve UI/UX while preserving functionality and artwork",
      "prompt": "Improve [screens] for [audience and task]. Preserve every existing working action, data contract, meaningful image and required content item. Inspect screenshots at phone and desktop widths first. Prioritize hierarchy, readable text, primary-action placement, navigation and recovery. Apply a coherent visual system using [specific reference qualities]. Condense oversized sections without deleting information or clipping controls; use appropriate disclosures for secondary detail. Improve component states, focus and purposeful motion with reduced-motion support. Test long labels, empty/error states and the primary flow after the changes. Return concrete before/after findings and evidence. Do not replace the whole hero or art collection to make the redesign easier."
    },
    {
      "id": "resume",
      "title": "Resume a long build without losing decisions",
      "prompt": "Resume [project] from its current specification, decision log and delivery note. First inspect the source, active work and most recent verified release so you do not overwrite unfinished changes or restart completed work. Summarize the intended outcome, completed MUST requirements, unresolved blockers, preserved assets and current source of truth. Continue the highest-value independent implementation task, then verify the affected flow and update the handoff. Do not repeat completed checks without a new change, failure or unresolved concern. Preserve previous user decisions and incorporate newer steering. Ask only for an answer that actually blocks progress. Report what was completed in this session and the exact next resumption point."
    }
  ],
  "example": {
    "title": "Worked feature contract: a service quote builder",
    "context": "A fictional local service business uses a browser-only estimator to prepare a scope. It does not take payment, book an appointment or send an email.",
    "rows": [
      [
        "REQ-01 / Configure",
        "Visitor selects one service and quantities.",
        "Service ID must exist; quantities are whole numbers 1–20.",
        "Selection is in browser state; totals are derived.",
        "Known items appear once with the correct quantity and total."
      ],
      [
        "REQ-02 / Extras",
        "Visitor adds optional extras.",
        "No duplicate extra IDs; incompatible extras explain the conflict.",
        "Extras update the same draft; derived total recalculates.",
        "Removing an extra changes the itemized and overall totals together."
      ],
      [
        "REQ-03 / Save draft",
        "Visitor chooses Save on this device.",
        "Persist non-sensitive configuration only; validate loaded schema.",
        "Local draft survives refresh when storage is available.",
        "With storage denied, show the failure and preserve an exportable in-memory draft."
      ],
      [
        "REQ-04 / Export",
        "Visitor chooses Download scope.",
        "Include services, quantities, sample price, assumptions and exclusions.",
        "Generate a text file; no remote send occurs.",
        "Downloaded content matches the visible selection; no false Sent confirmation."
      ],
      [
        "REQ-05 / Reset",
        "Visitor requests Reset.",
        "Confirm in-page; Cancel preserves everything.",
        "Clear only this draft after confirmation.",
        "Both UI and storage reset consistently; unrelated site data remains."
      ]
    ],
    "states": [
      "Empty: choose a service to begin.",
      "Invalid: explain which quantity needs correction and keep other inputs.",
      "Conflict: name incompatible extras and offer a choice.",
      "Persistence failure: say the draft is not saved and offer export.",
      "Success: say Scope downloaded only after the download is initiated.",
      "Production extension: a shared quote requires a server-owned ID, owner permissions, status and real persistence; local storage alone cannot deliver this."
    ],
    "bad": "Build an amazing business website with a quote form and make it work.",
    "better": "Build a quote workspace for a first-time customer on a phone. They choose one fictional service, set quantities and extras, see an itemized total, save a non-sensitive draft on this device and download an accurate scope. It must not claim to send, book or charge. Preserve the current artwork. Test duplicate extras, quantity limits, storage failure, refresh and 320px keyboard access."
  },
  "scorecard": [
    {
      "criterion": "Outcome and scope",
      "evidence": "A real user can finish the intended task."
    },
    {
      "criterion": "Working controls",
      "evidence": "Every visible action does what its label promises."
    },
    {
      "criterion": "State and persistence",
      "evidence": "Counts, details, saved values and refresh agree."
    },
    {
      "criterion": "Data and domain rules",
      "evidence": "Boundary calculations and valid transitions are correct."
    },
    {
      "criterion": "Permissions and privacy",
      "evidence": "Private resources are protected at the real trust boundary."
    },
    {
      "criterion": "Error and recovery",
      "evidence": "Failure preserves work and offers a useful next action."
    },
    {
      "criterion": "Mobile and readability",
      "evidence": "Important content and controls remain readable and reachable."
    },
    {
      "criterion": "Accessibility",
      "evidence": "Keyboard, labels, focus and relevant announcements work."
    },
    {
      "criterion": "Visual coherence",
      "evidence": "Hierarchy, type, imagery and components support the task."
    },
    {
      "criterion": "Performance",
      "evidence": "Media and interactions are appropriate to the tested device."
    },
    {
      "criterion": "Delivery",
      "evidence": "The actual delivered URL/entry point is usable."
    },
    {
      "criterion": "Evidence and handoff",
      "evidence": "Claims match performed checks and remaining gates are explicit."
    }
  ],
  "sources": [
    {
      "id": "openai",
      "title": "OpenAI · Prompting Codex",
      "url": "https://learn.chatgpt.com/docs/prompting#prompting-codex",
      "applied": "Name the desired behavior, provide relevant context, preserve constraints and say how to verify the change."
    },
    {
      "id": "frontend",
      "title": "OpenAI · Frontend prompt instructions",
      "url": "https://developers.openai.com/api/docs/guides/frontend-prompt",
      "applied": "Fit composition and controls to the audience and product domain; preserve an existing design system."
    },
    {
      "id": "claude",
      "title": "Anthropic · Claude Code best practices",
      "url": "https://code.claude.com/docs/en/best-practices",
      "applied": "Supply missing project context, keep durable instructions focused and provide runnable checks. Prompts alone do not enforce security boundaries."
    },
    {
      "id": "v0",
      "title": "Vercel · How to prompt v0",
      "url": "https://vercel.com/blog/how-to-prompt-v0",
      "applied": "Describe the product surface, context of use, constraints and taste instead of relying on vague adjectives."
    },
    {
      "id": "forms",
      "title": "W3C WAI · Validating input",
      "url": "https://www.w3.org/WAI/tutorials/forms/validation/",
      "applied": "Provide clear validation and recovery; client-side validation does not replace server checks for server-owned data."
    },
    {
      "id": "responsive",
      "title": "Google web.dev · Learn responsive design",
      "url": "https://web.dev/learn/design/",
      "applied": "Plan adaptable layouts, typography, images and input methods rather than treating mobile as a scaled desktop."
    },
    {
      "id": "authorization",
      "title": "OWASP · Authorization cheat sheet",
      "url": "https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html",
      "applied": "Enforce permissions at the trusted boundary, applying least privilege and checking access for each protected operation."
    },
    {
      "id": "idempotent",
      "title": "MDN · Idempotent operations",
      "url": "https://developer.mozilla.org/en-US/docs/Glossary/Idempotent",
      "applied": "Distinguish safe repetition from operations whose repeated side effects require deliberate duplicate protection."
    }
  ]
}