Connect a reporting request to a procedure and a product
A community craft studio combines registrations, attendance and refunds into a weekly activity report. Operations asks for “a backend where we can see reports,” without specifying whether revenue belongs to the payment week or the event week. Generating charts immediately would turn an unresolved definition into code. This example begins with that ambiguity and produces reviewable requirements, a repeatable procedure and one accepted prototype path. It imports no real customer records and launches no application.
The source has three substantive scenarios: clarifying requirements into a PRD, extracting repeated work into SOPs, and following a five-stage product-development process. Preserve their distinctions. A PRD describes required system behavior; an SOP describes how a particular task is performed; a running workflow also needs triggers, state and actual operators. Writing steps does not establish permissions, scheduling or failure recovery. Review and a “vibe check” need observable evidence rather than an encouraging impression.
Scenario one: turn the request into a reviewable PRD
Collect authorized meeting notes, current spreadsheets and an example report, with source dates. Separate confirmed facts, proposals, contradictions and gaps. “The manager mainly wants weekly revenue” is an input from a meeting, not automatic proof of every user's goal. Identify roles: operations reconciles records, the owner reads aggregates, and ordinary attendees do not access this backend.
Prioritize questions that alter the result: when the week starts, its time zone, treatment of cancellations and refunds, and whether a missing attendance entry establishes absence. Ask the highest-impact question while continuing independent organization. Do not fill business gaps silently. If the owner confirms reporting by event week with refunds attributed to that event, retain the rule version; payment-week cash movement is a different view.
The draft includes problem, users, scope, core flow, field definitions, exceptional states, permissions and acceptance. Automated gap analysis can identify a missing decision, but its suggestion remains unapproved until someone decides. Extending an existing PRD requires recording the changed rule, affected screens and old-record implications. A fluent inserted section must not quietly become a new requirement.
One fixture-based criterion is: “Activity A has three valid registrations and one full refund; the report displays the defined effective count and net amount, with traceable underlying records. An entry missing an amount appears in the exception list and is not silently counted as zero.” These are test inputs, not operating results. Deliver the PRD, a glossary and an open-question list, each question assigned an owner and an explanation of which next step it blocks.
Scenario two: extract a procedure from spoken experience
Ask an operator to describe one complete reporting run, including last week's rework, rather than only the ideal sequence. Capture trigger, input files, versions, actions, checkpoints, output and next owner. A transcript saying “process that sheet again” needs the sheet identity and transformation clarified. Attractive headings cannot repair missing operational detail.
The example SOP exports permitted test data, preserves the original with its timestamp, checks columns and activity IDs, normalizes date representation, matches refunds using the approved rule, creates a proposed aggregate, reviews exceptions and publishes only an approved report. Give every step prerequisites and stop conditions. A refund without an activity ID cannot simply be attached to another row with the same amount; it enters a reconciliation queue.
Write branches explicitly. A repeated refund row could be a duplicate export or two genuine partial refunds. Examine transaction identifiers and source records before removing anything. If an input file is absent, pause the affected part and report incompleteness instead of inventing a replacement. The procedure, branch diagram and execution checklist should reference the same rule revision so the easiest-looking artifact cannot drift away from the actual method.
A quality score can highlight missing inputs or checkpoints; it does not demonstrate executability. Have a second operator process one redacted sample using only the SOP. Record every point requiring an oral explanation, repair the document and repeat that portion. Removing redundant actions is useful, but deleting an accounting review simply to shorten the procedure removes a control rather than waste.
Translate the SOP into bounded automation opportunities
Classify actions as deterministic processing, judgment and external writes. Column checks and joins on a defined identifier are good early candidates. Conflicting refund attribution belongs with operations. Publishing a report is a consequential write with its own approval state. The first automation may produce only a draft and exception list; it need not simultaneously connect scheduling, email and every source system.
Use a revisable roadmap: one fixture run, a small manually triggered pilot, and scheduling only after the behavior is understood. The source proposes a ninety-day plan and ROI forecasts; neither a fixed duration nor a model's financial projection is a commitment for this studio. Record manual work, review time, exception handling, maintenance and service charges across comparable runs. Fewer clicks do not necessarily mean the same proportional reduction in total work.
A workflow needs a run_id, input versions, current step, approval state and rerun policy. After an export timeout, check whether a file already exists. After a publication timeout, verify the result before sending again. Specify which artifacts survive a partial failure, who resolves exceptions and when retries stop. If there is no configured scheduler, say “manual execution”; a time written in an SOP is not an installed recurring job.
Scenario three: give each development stage an exit condition
Requirements accept the reviewed PRD and limit the prototype to uploading a fixture, viewing proposed aggregates and inspecting exceptions. Architecture compares extending an existing tool with a separate prototype, considering maintenance, storage and access. GitHub's MADR is a relevant lightweight reference for recording a design choice. Borrow the practice of keeping context, alternatives and rationale; there is no need to install another application merely to write a decision. The template cannot choose the architecture for the team.
Code generation implements one complete path: read a file, validate it, calculate a result and display exceptions. Use isolated fixtures, read-only originals and a separate output file. The task specifies allowed changes and excluded features. Explain new dependencies and versions, and label simulated endpoints as unconnected. A screen that resembles a reporting backend is not evidence of correct totals; reconcile each result against the fixture.
Debugging begins with the failing input, revision, run command and expected outcome. If a refund is subtracted twice, trace import, matching and aggregation to the first duplicate. Do not rewrite the entire backend as the first response. After the repair, rerun the failing fixture and neighboring branches, including two valid partial refunds that must remain distinct. Iteration accepts one reviewed change, such as an activity filter, and rechecks existing totals so a new control cannot silently change reporting definitions.
Deployment preparation separately covers environment variables, access control, backups, health checks and recovery. Generating instructions is not deployment, and a passing test mode is not a passing production environment. Reverting code may not undo changed data. Rehearse migrations and recovery on an isolated copy. This example creates no account, publishes no report and performs no production deployment.
Place a verified Skill at a precise checkpoint
Webapp Testing fits local browser acceptance of the prototype. After the app is running, inspect the rendered DOM, identify upload and filter controls, verify exceptions and displayed results, and capture screenshots and logs. Prerequisites are Python, Playwright, the appropriate browser binaries, a startup command and approved fixtures. The Skill does not extract the entire business SOP or independently validate accounting definitions and server-side calculations.
A browser acceptance request can check that a valid sample displays an aggregate, a missing activity ID produces an exception, changing a filter preserves the relevant warning, and refresh behavior matches the PRD. Deterministic calculation checks supply another layer of evidence. The detail page exposes a pinned source and Apache-2.0 license evidence. Static source inspection does not establish that this application was tested or security-certified.
The source's six package names have not been established here as matching, source-verifiable SkillPI records. Do not invent links from their names. To discover another candidate, state the actual gap—for example, extracting exception-aware SOPs from a redacted process transcript—then inspect source, SKILL.md, license, access and dependencies. Trial one recoverable sample. Record discovery, installation, invocation and artifact acceptance separately instead of treating an installation success message as the result.
Give the agent a reproducible task packet
Supply four inputs: approved reporting definitions v2, fixtures, allowed changes and acceptance conditions. An extraction request might say: “Turn this transcript into an SOP. Separate confirmed rules from suggestions. For each action specify input, action, output and stop condition. Put missing information in an open-question list. Connect no external account and publish nothing.” Pass the confirmed revision to the coding stage rather than freezing the earliest discussion as permanent requirements.
Every iteration returns a change summary, files, business-rule changes, checks actually run and unverified items. Preserve the last accepted checkpoint so another operator can resume. If the issue concerns publication, do not simultaneously rewrite importing. Separate goals keep regression scope and recovery understandable. A complete handoff allows a reviewer to identify what was designed, what executed and what remains only a proposal.
Troubleshooting and frequently asked questions
Why does the PRD never finish? Check whether a growing list of questions has replaced a minimal user path and its blocking decisions. Why can nobody follow a polished SOP? Trial it with a new operator and locate implicit knowledge or unavailable inputs. Why are savings disappointing? Review whether approval, exceptions and maintenance offset the automated work; narrow the pilot before claiming benefits.
Can a nontechnical owner proceed? They can define business rules and observable acceptance, while architecture, permissions and data recovery still need relevant competence. Can they ignore code? They may write fewer lines, but must understand change scope and verification evidence; the appearance of a correct page cannot establish data integrity or authorization. Must a workflow be fully AI-driven? No. People and deterministic scripts can form a workflow. Clarify responsibility and exception behavior before adding intelligent steps.
Sources
The English source supplies the three scenarios and five-stage scope. This independent reporting example does not repeat its install counts or safety assurances. MADR is the GitHub reference for lightweight decision documentation; its public README offers MIT or CC0 licensing. The pinned Webapp Testing source supports the local interface-checking method. No listed tool was installed or executed for this article; the run outcomes described above are acceptance designs.