[{"data":1,"prerenderedAt":4429},["ShallowReactive",2],{"article-customer-paid-invoice-still-open":3,"related-articles-customer-paid-invoice-still-open":94},{"id":4,"title":5,"author":6,"body":7,"category":70,"description":71,"extension":72,"featured":73,"heroImage":74,"meta":75,"navigation":76,"path":77,"publishedAt":78,"readingTime":79,"relatedAgents":80,"relatedArticles":81,"relatedWorkflows":84,"searchIntent":85,"seo":86,"stem":87,"topics":88,"updatedAt":78,"visual":92,"__hash__":93},"articles\u002Farticles\u002Fcustomer-paid-invoice-still-open.md","A customer paid. Why is the invoice still open?","StackOS team",{"type":8,"value":9,"toc":63},"minimark",[10,14,17,22,25,28,32,35,38,41,44,48,51,54,57,60],[11,12,13],"p",{},"A payment reminder can be factually defensible and still be the wrong next move. An invoice is open, but money may already have arrived and still need matching. The customer may have promised a date, raised a dispute, or heard from the business yesterday. For a solo entrepreneur, those are not details to sort out after the reminder goes out.",[11,15,16],{},"In a proposed agent-managed follow-up workflow, the job begins by checking what was received and what remains due. The agent then decides whether to send an authorized reminder, wait under an existing agreement, or bring the owner a question it cannot resolve from the records.",[18,19,21],"h2",{"id":20},"give-the-agent-the-facts-and-authority-to-act","Give the agent the facts and authority to act",[11,23,24],{},"Before it can do that, the agent needs access to a confirmed payment source, the invoice and agreed terms, any allocations already made, and the latest promise, dispute, or contact. It also needs connected tools that can inspect those records and perform the permitted routine updates, along with the owner's rules for customer contact.",[11,26,27],{},"“Follow up on open invoices” supplies neither the evidence nor the authority. If the agent cannot inspect the current inputs, or if its routine actions and message boundary are not configured, it should return a focused question rather than manufacture a tidy status.",[18,29,31],{"id":30},"match-the-payment-before-asking-for-the-balance","Match the payment before asking for the balance",[11,33,34],{},"Take a hypothetical invoice for $1,000. Assume a confirmed $400 payment, no earlier payments or adjustments, and a match between that payment and this invoice. The remaining balance is $600.",[11,36,37],{},"The arithmetic comes after the match. The agent compares the payment reference and amount with the invoice, the work covered by the agreed terms, and any prior allocation. It checks whether the money has already been recorded. If the match is clear and the update is supported within its authority, it records money that was already received; it does not initiate a new payment. It then checks the invoice balance again instead of marking the whole invoice paid.",[11,39,40],{},"The agent passes that confirmed result to the cashflow and follow-up work: $400 received, $600 still open. It checks that those records reflect the result. Any failed update remains identified as unfinished.",[11,42,43],{},"If a $400 payment might fit two invoices, the agent keeps the allocation and affected reminder on hold and asks which invoice the payment covers. An attempted update with an uncertain result also needs investigation before another write. The agent should check the existing payment record rather than assume that a missing confirmation means nothing was saved.",[18,45,47],{"id":46},"the-remaining-balance-does-not-settle-the-contact-decision","The remaining balance does not settle the contact decision",[11,49,50],{},"In the example, the balance check establishes $600 outstanding. Whether it is time to ask for it depends on the agreement and the conversation.",[11,52,53],{},"The agent now reads the current promise, dispute, and recent-contact context against the owner’s rules. A customer who gave a payment date may need time until that date. A dispute may require the routine collection path to pause. A recent message may make another reminder inappropriate for this particular situation. None of those conditions creates a universal contact policy; each changes this one decision.",[11,55,56],{},"When the latest information satisfies the owner's rule for a routine follow-up, the agent can send the authorized message through its connected delivery tool and inspect the delivery result. A failed or unconfirmed send stays visible; drafting a message is not evidence that it was sent. When the payment remains ambiguous or the conversation changes what a reminder would mean, the agent pauses that contact and brings the owner the question needed to continue.",[11,58,59],{},"After the owner answers, the agent resumes the same item and checks the payment, invoice, and contact state again before acting.",[11,61,62],{},"An agreed installment illustrates the final decision. The invoice can remain open while the agent waits for the agreed date, with the payment already received recorded against it. The next action is to check again when the agreement calls for it. There is no reason to invent a collection problem merely to finish today's task with a sent message.",{"title":64,"searchDepth":65,"depth":65,"links":66},"",2,[67,68,69],{"id":20,"depth":65,"text":21},{"id":30,"depth":65,"text":31},{"id":46,"depth":65,"text":47},"AI operations","A proposed payment-follow-up agent can match received money, preserve an open balance, and choose the next contact decision for a solo entrepreneur.","md",false,null,{},true,"\u002Farticles\u002Fcustomer-paid-invoice-still-open","2026-09-06","4 min read",[],[82,83],"building-ai-finance-department-one-person-business","when-is-a-receipt-actually-processed",[],"Understand how a proposed payment-follow-up agent can match a payment to an invoice and decide whether a solo entrepreneur should send a reminder",{"title":5,"description":71},"articles\u002Fcustomer-paid-invoice-still-open",[89,90,91],"AI finance operations","AI agents for solo entrepreneurs","payment follow-up","none","PhkJH5CcCG7HgS1o7fPD1h8qH_vJrNA78dYDcwk1bfg",[95,201,247,381,454,598,708,877,1073,1226,1528,1845,2536,2987,3254,3551,3784,3967,4142],{"id":96,"title":97,"author":6,"body":98,"category":70,"description":186,"extension":72,"featured":73,"heroImage":74,"meta":187,"navigation":76,"path":188,"publishedAt":78,"readingTime":189,"relatedAgents":190,"relatedArticles":191,"relatedWorkflows":194,"searchIntent":195,"seo":196,"stem":197,"topics":198,"updatedAt":78,"visual":92,"__hash__":200},"articles\u002Farticles\u002Fbuilding-ai-finance-department-one-person-business.md","Building an AI finance department for a one-person business",{"type":8,"value":99,"toc":180},[100,103,106,110,113,116,119,122,125,129,132,154,157,161,164,167,171,174,177],[11,101,102],{},"I wanted agents to take on the bookkeeping, invoices, and follow-ups that keep interrupting a solo business. Asking for a summary is only part of that request. I also want the work carried through after I answer a question.",[11,104,105],{},"I would start with one finance coordinator: an agent responsible for the recurring job and any narrower tasks it delegates. You give it the outcome and agreed boundaries. It carries the case forward, checks what happened, and returns a precise question when those boundaries no longer cover the situation.",[18,107,109],{"id":108},"start-with-a-complete-job-not-a-finance-inbox","Start with a complete job, not a finance inbox",[11,111,112],{},"Consider a common request: send an agreed invoice, follow up if it remains unpaid, and update the picture once money arrives.",[11,114,115],{},"Before the work begins, the owner gives it a small operating frame: approved customer terms, the records it may use, where payments and commitments are visible, routine messages it may send, and the circumstances that require a return to the owner. Those facts let an agent distinguish ordinary collection work from a change in the commercial relationship.",[11,117,118],{},"Now imagine a customer pays part of an invoice. The coordinator compares the payment reference, amount, open balance, and prior conversation. With tools connected for these jobs, and a clear match within its authority, it can record the partial payment and check the invoice again to confirm the remaining balance. That result goes into the short-term cash view and the follow-up task, so the next message does not ask for money already received. If an update fails, the coordinator reports which part remains unfinished.",[11,120,121],{},"If two open invoices could fit the same payment, the coordinator should not choose whichever record is easiest to close. It returns the case with the relevant options and asks which invoice the payment belongs to. Once you answer, it resumes from that answer rather than making you reconstruct the situation in a second conversation.",[11,123,124],{},"Here, agentic work means following the case through: using connected inputs, choosing the next permitted step, checking the result, and preserving an open question when the work cannot continue.",[18,126,128],{"id":127},"the-coordinator-owns-the-case-specialists-can-be-behind-it","The coordinator owns the case; specialists can be behind it",[11,130,131],{},"In this setup, one coordinator owns the owner-facing case and calls on narrower help as needed:",[133,134,135,139,142,145,148,151],"ul",{},[136,137,138],"li",{},"A receipt task can retain the original document, extract available details, check a likely duplicate, and return the missing business-purpose question.",[136,140,141],{},"A bookkeeping task can assemble period inputs and isolate transactions that do not fit the existing information.",[136,143,144],{},"An invoice task can prepare or send an invoice only from agreed terms and the authority you gave it.",[136,146,147],{},"A collection task can keep payment, invoice, customer context, and follow-up state together.",[136,149,150],{},"A cashflow task can refresh a near-term view from known expected receipts and commitments while leaving uncertainty visible.",[136,152,153],{},"A tax-preparation task can organize records and unanswered questions for qualified review; it does not interpret tax treatment, file a return, or replace professional advice.",[11,155,156],{},"The owner should experience this as one conversation: “What needs attention this week?” The coordinator brings the work back together. Otherwise the entrepreneur becomes the integration layer, pasting context between a receipt agent, an invoice agent, and a cashflow agent.",[18,158,160],{"id":159},"decide-what-the-agent-may-finish-without-you","Decide what the agent may finish without you",[11,162,163],{},"A better boundary than approving every keystroke is explicit permission. An owner might authorize the coordinator to save an original receipt, prepare a routine invoice from fixed terms, send a previously approved reminder, record an unambiguous payment, or update a cash view from existing inputs. The owner keeps decisions that change price, scope, customer commitments, disputed payments, ambiguous business purpose, or spending priorities. A qualified professional keeps professional accounting, tax, and legal judgment.",[11,165,166],{},"Different businesses will choose different boundaries. The important thing is that the agent can see the boundary while it has the case in hand. “Ask me when something feels unusual” is not a reliable instruction. “Ask before changing agreed terms, contacting a customer after a dispute, or assigning a payment with more than one plausible invoice” gives it a usable stopping rule.",[18,168,170],{"id":169},"give-it-a-real-starting-point-and-a-way-to-continue","Give it a real starting point and a way to continue",[11,172,173],{},"An agent cannot take over recurring work from a paragraph of wishes. It needs a configured way to begin: an owner-started weekly run, a receipt delivered through the chosen intake channel, or an enabled scheduled check. It also needs a designated place to read current records and leave the result for the next step.",[11,175,176],{},"Start with one repetitive path, the information it may consult, the actions it may take, and the questions that must come back to you. Test ordinary and awkward cases: a blurred receipt, changed client agreement, partial payment, or uncertain commitment. The test is whether you can see what happened, correct it when needed, and let the next run continue without a scavenger hunt.",[11,178,179],{},"The first finance coordinator may handle only invoice follow-up or receipt intake. After resolving an unclear case, return in a fresh session and ask what remains open. Check whether the agent retrieves your decision, shows the confirmed result, and continues the permitted work without asking you to explain the case again.",{"title":64,"searchDepth":65,"depth":65,"links":181},[182,183,184,185],{"id":108,"depth":65,"text":109},{"id":127,"depth":65,"text":128},{"id":159,"depth":65,"text":160},{"id":169,"depth":65,"text":170},"A practical design for AI-supported finance operations in a one-person business, with clear authority, verification, and escalation boundaries.",{},"\u002Farticles\u002Fbuilding-ai-finance-department-one-person-business","6 min read",[],[192,193],"ai-agent-experience","what-is-an-agentic-workflow",[],"Learn how to design an AI finance coordinator for a one-person business without handing over owner or professional judgment",{"title":97,"description":186},"articles\u002Fbuilding-ai-finance-department-one-person-business",[89,90,199],"agentic workflows","zQb-2ifRwHwT8i9Z8gTCawiPTMSUzf4ReJ9_4mhXb5w",{"id":4,"title":5,"author":6,"body":202,"category":70,"description":71,"extension":72,"featured":73,"heroImage":74,"meta":241,"navigation":76,"path":77,"publishedAt":78,"readingTime":79,"relatedAgents":242,"relatedArticles":243,"relatedWorkflows":244,"searchIntent":85,"seo":245,"stem":87,"topics":246,"updatedAt":78,"visual":92,"__hash__":93},{"type":8,"value":203,"toc":236},[204,206,208,210,212,214,216,218,220,222,224,226,228,230,232,234],[11,205,13],{},[11,207,16],{},[18,209,21],{"id":20},[11,211,24],{},[11,213,27],{},[18,215,31],{"id":30},[11,217,34],{},[11,219,37],{},[11,221,40],{},[11,223,43],{},[18,225,47],{"id":46},[11,227,50],{},[11,229,53],{},[11,231,56],{},[11,233,59],{},[11,235,62],{},{"title":64,"searchDepth":65,"depth":65,"links":237},[238,239,240],{"id":20,"depth":65,"text":21},{"id":30,"depth":65,"text":31},{"id":46,"depth":65,"text":47},{},[],[82,83],[],{"title":5,"description":71},[89,90,91],{"id":248,"title":249,"author":6,"body":250,"category":70,"description":365,"extension":72,"featured":73,"heroImage":74,"meta":366,"navigation":76,"path":367,"publishedAt":78,"readingTime":189,"relatedAgents":368,"relatedArticles":370,"relatedWorkflows":372,"searchIntent":375,"seo":376,"stem":377,"topics":378,"updatedAt":78,"visual":92,"__hash__":380},"articles\u002Farticles\u002Fmanaging-a-solo-agency-with-ai-agents.md","Managing a solo agency with AI agents",{"type":8,"value":251,"toc":358},[252,255,258,262,265,268,271,274,278,281,284,287,291,294,297,300,317,321,334,342,345,349,352,355],[11,253,254],{},"One client can have a website project in final review and a campaign waiting for a different decision. Each has its own scope, deadlines, and unfinished work. An agent reading “everything about this client” needs a way to tell those engagements apart.",[11,256,257],{},"Here is a proposed arrangement for a solo agency: keep a short agency brief, give each active engagement its own working record, and use a coordinating agent for decisions that cross projects. Finance serves the company across those engagements. Each job should specify what the agent reads, the work it may carry out, and what it must report back.",[18,259,261],{"id":260},"give-the-agency-agent-a-short-business-brief","Give the agency agent a short business brief",[11,263,264],{},"The agency brief should answer agency questions: who the business is, how the owner wants work handled, the current engagements, and commitments that affect more than one of them. It should say which decisions the owner retains, such as changing a price or promising an earlier delivery date.",[11,266,267],{},"It should not hold every scope document, draft, message, and old decision. When material matters only to one piece of client work, it belongs with that engagement.",[11,269,270],{},"An agency agent could use that brief to review upcoming commitments and identify where the owner needs to make a decision. The project records would remain the source for detailed status; the agency view would link to them instead of keeping a second account of every task.",[11,272,273],{},"The setup also needs working access and a way to start each job. For example, the owner could ask for a commitments review, or an agreed schedule could start it. The agent needs permission to read the selected project records and a place to deliver its findings. Writing those instructions does not itself connect the accounts or start a recurring process.",[18,275,277],{"id":276},"let-each-engagement-carry-its-own-active-work","Let each engagement carry its own active work",[11,279,280],{},"Consider a hypothetical client with two engagements: a site launch and a recruiting campaign. The launch agent reads that engagement’s agreed scope, current decisions, work due, and client inputs still needed. It can assemble a status, surface a missing approval, or prepare the next permitted item from the information it can see. Its return might say that copy is ready for approval, image selection remains open, and the launch date depends on that decision.",[11,282,283],{},"The campaign has its own brief and progress report. A question about its audience belongs there. Where the engagements depend on the same person's approval or compete for the owner's time, the project agent should raise that conflict for coordination.",[11,285,286],{},"Later work can start from accepted scope and unresolved questions instead of a generic client thread.",[18,288,290],{"id":289},"coordinate-where-commitments-meet","Coordinate where commitments meet",[11,292,293],{},"Some work has no honest home inside a single engagement. A delivery date may affect another project. A client’s delayed input may change two commitments. The owner may need to choose which of several client conversations comes first.",[11,295,296],{},"In this arrangement, the coordinating agent reads the affected projects' reports and checks the commitments behind them. Suppose, in the hypothetical example, both engagements need a client decision before Friday, but the owner has time to prepare only one review. The agent should bring back the two deadlines, the work each review would unblock, and the decision needed. It should not silently move a promised date to make the plan fit.",[11,298,299],{},"After the owner chooses a priority, the agent can update the permitted working plan and check that the affected project records reflect the decision. Any client message or revised commitment still follows the owner's rules for that action.",[11,301,302,303,310,311,316],{},"This resembles a general orchestration pattern where a central agent delegates bounded work, synthesizes returns, and brings judgment back to a person. ",[304,305,309],"a",{"href":306,"rel":307},"https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents",[308],"nofollow","Anthropic’s overview of effective agents"," describes that pattern; it is not proof that this agency design will work. More agents also add coordination overhead and failure paths, as ",[304,312,315],{"href":313,"rel":314},"https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Farchitecture\u002Fai-ml\u002Fguide\u002Fai-agent-design-patterns",[308],"Microsoft’s orchestration guidance"," notes. A coordinator should appear when commitments truly cross, not because every business needs a fixed roster.",[18,318,320],{"id":319},"keep-finance-at-the-company-level","Keep finance at the company level",[11,322,323,324,328,329,333],{},"Finance is shared business work. An agency can use one external financial source of truth across its engagements; a standalone business can use the same arrangement. Work such as ",[304,325,327],{"href":326},"\u002Flibrary\u002Fworkflows\u002Ffinance-receipt-intake\u002F","receipt intake"," and ",[304,330,332],{"href":331},"\u002Flibrary\u002Fworkflows\u002Ffinance-payment-request-followups\u002F","payment follow-ups"," belongs here, even when an item relates to a particular project.",[11,335,336,337,341],{},"A ",[304,338,340],{"href":339},"\u002Flibrary\u002Fagents\u002Fstackos-finance-bookkeeping-preparer\u002F","bookkeeping preparation agent"," can prepare or check a financial record from the source it is authorized to consult and, when evidence supports it, associate that record with an engagement. The association is a label, not another financial master, a split allocation, or permission to guess. A company-wide expense stays company-wide without a source-backed engagement. If it might relate to several projects, the uncertainty returns as a question.",[11,343,344],{},"The same client can have several engagements, so a customer name alone is not enough to establish financial attribution. Agency context also does not grant access to a client’s books or combine separate businesses into one financial picture. The financial source, the engagement reference, and the authority to act each need to be resolved independently.",[18,346,348],{"id":347},"use-the-next-item-to-test-its-placement","Use the next item to test its placement",[11,350,351],{},"Before naming another agent, take one real piece of work and ask where it belongs. If it concerns one engagement’s scope, state, or outstanding decision, begin there. If it compares commitments across engagements, bring it to the agency coordination point. If it changes or prepares a company financial record, keep the source of truth at the business level. Client-owned data or work for a separate business needs separately defined scope and access.",[11,353,354],{},"Then make the operating question concrete: what may the agent read, what may it do, what must it return, and which decision still belongs to the owner? Prompts alone will not answer those questions. The arrangement starts to earn its place when a real item can enter through a configured path, produce a checkable result, and leave an unresolved decision visible.",[11,356,357],{},"It will not fix commitments that were never made clear. The remaining test is smaller: can the next ambiguous item be placed without copying context, guessing attribution, or asking the owner to reconstruct work that already has a home?",{"title":64,"searchDepth":65,"depth":65,"links":359},[360,361,362,363,364],{"id":260,"depth":65,"text":261},{"id":276,"depth":65,"text":277},{"id":289,"depth":65,"text":290},{"id":319,"depth":65,"text":320},{"id":347,"depth":65,"text":348},"A proposed way to organize a solo agency with AI agents, keeping engagement work, cross-project commitments, and company finance in clear working contexts.",{},"\u002Farticles\u002Fmanaging-a-solo-agency-with-ai-agents",[369],"stackos-finance-bookkeeping-preparer",[82,83,371],"customer-paid-invoice-still-open",[373,374],"finance-receipt-intake","finance-payment-request-followups","Learn how to organize AI agents for a solo agency across client engagements, agency coordination, and shared company finance",{"title":249,"description":365},"articles\u002Fmanaging-a-solo-agency-with-ai-agents",[90,379,199],"agency operations","6Yin2exXGzK2j4Zs6Yz7IF3MFmL4K3kz_oeLbgqPryY",{"id":382,"title":383,"author":6,"body":384,"category":70,"description":442,"extension":72,"featured":73,"heroImage":74,"meta":443,"navigation":76,"path":444,"publishedAt":78,"readingTime":445,"relatedAgents":446,"relatedArticles":447,"relatedWorkflows":448,"searchIntent":449,"seo":450,"stem":451,"topics":452,"updatedAt":78,"visual":92,"__hash__":453},"articles\u002Farticles\u002Fwhen-is-a-receipt-actually-processed.md","When is a receipt actually processed?",{"type":8,"value":385,"toc":437},[386,389,392,396,399,402,405,409,412,418,421,424,428,431,434],[11,387,388],{},"Imagine forwarding an email with two receipts to an agent. It can read one attachment; the other will not open. Calling the email “processed” hides the difference. Waiting for both to be readable leaves the first receipt unprepared.",[11,390,391],{},"For a solo entrepreneur, the useful question is whether the work can move forward without pretending that every question has been answered. A proposed receipt agent can do that when it has a configured way to receive a forwarded email or manual upload, access to the retained receipt records it is allowed to consult, and a clear boundary for routine intake work.",[18,393,395],{"id":394},"one-email-can-become-two-separate-receipt-paths","One email can become two separate receipt paths",[11,397,398],{},"The agent retains the email and both original attachments. It can open the first receipt, so it extracts the date, vendor, and amount that the document actually shows. The second attachment stays unreadable.",[11,400,401],{},"Those are now two items with different states. The readable receipt can continue through intake. The unreadable one stays attached to the same source with a visible reason it cannot yet be prepared. The agent does not need to wait for a perfect email before making the completed part available.",[11,403,404],{},"It also checks the readable item against the receipt records already available to it. An exact, verified duplicate can point to the existing receipt, with a note explaining that it arrived again. A document with a similar vendor, date, or amount is only a possible match. The agent keeps both originals while it checks whether they represent the same purchase.",[18,406,408],{"id":407},"the-owners-reply-belongs-to-the-item-that-needed-it","The owner’s reply belongs to the item that needed it",[11,410,411],{},"The readable receipt has another gap: the document itself does not say why the business incurred the expense. The agent can ask one focused question instead of assigning a purpose:",[413,414,415],"blockquote",{},[11,416,417],{},"“I retained the readable receipt and extracted its date, vendor, and amount. What was the business purpose? The second attachment cannot be read; can you send a readable copy?”",[11,419,420],{},"The owner replies, “The readable receipt was for materials for a workshop. I’ll resend the other one.” The agent links that answer to the readable receipt. The second item stays open. When its replacement arrives, the agent should attach it to that same item, inspect it, and resolve the missing-copy question only if the replacement is readable.",[11,422,423],{},"The agent owns that continuation. Its instructions cover which routine actions it may finish and which questions need the owner. With that permission in place, each save or extraction need not trigger another approval request. An uncertain match or missing business explanation still needs to be resolved before it becomes an accepted fact.",[18,425,427],{"id":426},"the-handoff-is-ready-for-bookkeeping-not-a-bookkeeping-decision","The handoff is ready for bookkeeping, not a bookkeeping decision",[11,429,430],{},"Before reporting the readable receipt ready, the agent should reopen the saved original, compare the extracted details with it, and confirm that the bookkeeping handoff points to the retained document and the owner's answer. If saving or checking fails, the item stays unfinished. While the replacement is still awaited, the broken attachment remains a separate missing-copy question.",[11,432,433],{},"That handoff does not decide how the expense belongs in the books, post a transaction, or settle tax treatment. Receipt intake prepares evidence and preserves uncertainty. Bookkeeping preparation uses that evidence alongside the business’s existing records and its own review boundaries.",[11,435,436],{},"The handoff for this example could be short: “Workshop-materials receipt ready for bookkeeping review, with the original and your explanation attached. The second attachment is awaiting a readable replacement.” When that replacement arrives, the agent has an existing item to finish—not another purchase to create.",{"title":64,"searchDepth":65,"depth":65,"links":438},[439,440,441],{"id":394,"depth":65,"text":395},{"id":407,"depth":65,"text":408},{"id":426,"depth":65,"text":427},"A proposed receipt agent can separate readable documents, preserve unresolved attachments, and prepare a clear handoff for a solo entrepreneur.",{},"\u002Farticles\u002Fwhen-is-a-receipt-actually-processed","3 min read",[],[82,192],[],"Understand how a proposed receipt agent for a solo entrepreneur can prepare receipt evidence without making bookkeeping decisions",{"title":383,"description":442},"articles\u002Fwhen-is-a-receipt-actually-processed",[89,90,327],"ss9JQi0_o4oqo9jg3uLFCxSbr_CJ495Ao-XmGd4xNME",{"id":455,"title":456,"author":6,"body":457,"category":70,"description":573,"extension":72,"featured":73,"heroImage":74,"meta":574,"navigation":76,"path":575,"publishedAt":576,"readingTime":189,"relatedAgents":577,"relatedArticles":580,"relatedWorkflows":584,"searchIntent":588,"seo":589,"stem":590,"topics":591,"updatedAt":576,"visual":92,"__hash__":597},"articles\u002Farticles\u002Fhow-to-separate-issue-investigation-from-implementation.md","How to separate issue investigation from implementation",{"type":8,"value":458,"toc":566},[459,462,465,473,476,480,483,492,495,502,506,509,512,515,519,522,529,538,542,545,553,556,559,563],[11,460,461],{},"An investigation conclusion can be persuasive enough to make the next move feel obvious. The evidence points to a likely cause. Some alternatives have been eliminated. A fix direction even seems to suggest itself.",[11,463,464],{},"That still does not answer the delivery question: should this change be made, by whom, with what scope, and against which acceptance and verification conditions?",[11,466,467,468,472],{},"For the current StackOS support-to-delivery contract, those are different records with different decision rights. The investigation records what the evidence supports. An operator instruction authorizes delivery work. Engineering takes ownership after that handoff has created delivery-ready state. When evidence remains incomplete, the investigation can close as ",[469,470,471],"code",{},"bounded_uncertainty"," only with its limit and next diagnostic named. That conclusion still leaves the delivery choice with the operator.",[11,474,475],{},"The distinction is small in prose and consequential in the record. Without it, a diagnosis can quietly acquire scope, authority, and implementation commitments that nobody explicitly chose.",[18,477,479],{"id":478},"let-the-investigation-stop-at-what-it-knows","Let the investigation stop at what it knows",[11,481,482],{},"In the current StackOS method, an investigation record carries the reported and expected behavior, gathered evidence, reproduction work, affected scope, facts, inferences, eliminated hypotheses, and residual uncertainty. Its purpose is to establish the condition under investigation and the limit of the evidence.",[11,484,485,486,488,489,491],{},"The current StackOS investigation workflow makes that boundary explicit. It can conclude with a verified cause, ",[469,487,471],{},", or no issue. A ",[469,490,471],{}," conclusion names the unresolved limit and the next diagnostic step; the workflow then returns the decision about delivery rather than creating a task or changing production behavior itself.",[11,493,494],{},"That produces a useful conclusion without converting a likelihood into a plan. “The evidence supports this likely failing path; this observation remains unconfirmed” belongs in the investigation record. “Implement this correction” requires a new decision.",[11,496,497,498,501],{},"Verified root cause is one conclusion state, not a prerequisite for closing an investigation. ",[469,499,500],{},"Bounded_uncertainty"," can lead to more diagnostics, a decision to leave delivery unopened, or a later operator decision to create narrowly scoped work. The conclusion carries the uncertainty forward; it does not choose among those responses.",[18,503,505],{"id":504},"authorization-changes-the-kind-of-work-being-done","Authorization changes the kind of work being done",[11,507,508],{},"The next record states that an accountable operator has decided to create delivery work from the conclusion. In the current StackOS handoff contract, task creation requires both a completed conclusion and a current instruction in the same canonical thread. The instruction supplies authority for a different action; it adds no new evidence about the cause.",[11,510,511],{},"The operator can request another diagnostic, leave product work unopened, or authorize a delivery task that preserves uncertainty in its context. The investigation record supports those choices; it does not select one by sounding compelling.",[11,513,514],{},"The handoff changes the active question from “What do we know?” to “What work is authorized now?” It preserves the evidence trail and the operator’s decision for the record that follows.",[18,516,518],{"id":517},"delivery-begins-when-implementation-can-be-evaluated","Delivery begins when implementation can be evaluated",[11,520,521],{},"Within the current StackOS delivery contract, engineering begins from a record that carries the conclusion and its limits alongside affected surfaces, an authorized direction, scope, acceptance criteria, verification expectations, dependencies, and residual risk. Those fields let engineering evaluate an implementation decision instead of reconstructing one from a support conclusion.",[11,523,524,525,528],{},"Its delivery-handoff workflow preserves the conclusion and safe thread references, creates tracker work after the same-thread instruction, and then hands implementation to ",[469,526,527],{},"engineering.tracked-delivery",". That is current StackOS contract evidence: it establishes this system’s boundary without supplying adoption or outcome evidence.",[11,530,531,532,537],{},"The FDA-published ",[304,533,536],{"href":534,"rel":535},"https:\u002F\u002Fwww.fda.gov\u002Fmedical-devices\u002Fmedical-device-single-audit-program-mdsap\u002Fmdsap-qms-p0009-nonconformity-and-corrective-action-procedure",[308],"MDSAP nonconformity and corrective-action procedure"," shows a similar record boundary in a medical-device quality-system context. Cause investigation precedes the development and implementation of corrective action, while action planning records roles, resources, acceptance criteria, and verification or validation. It is a domain-specific example, not general operating or legal guidance; its value here is to show that a finding about cause and a planned corrective action carry different obligations.",[18,539,541],{"id":540},"urgent-containment-is-a-separate-lane","Urgent containment is a separate lane",[11,543,544],{},"A cause-first sequence cannot cover every response that may be required while evidence is still developing.",[11,546,547,552],{},[304,548,551],{"href":549,"rel":550},"https:\u002F\u002Ftsapps.nist.gov\u002Fpublication\u002Fget_pdf.cfm?pub_id=957258",[308],"NIST CSF 2.0"," treats incident analysis, mitigation, and recovery as distinct outcomes while allowing related functions to occur concurrently. WHO’s complaints-handling guidance for manufacturers of prequalified in vitro diagnostics likewise describes circumstances in which corrective action may be needed before definitive root-cause identification. Together, those examples show that a response record can run alongside investigation without turning an unverified hypothesis into a corrective plan.",[11,554,555],{},"When containment is warranted, its authority, scope, and verification belong in a separate record. It can run concurrently with investigation. A root-cause corrective implementation makes a different claim: that the selected change addresses the cause and can be evaluated against its acceptance conditions.",[11,557,558],{},"The current StackOS evidence used here establishes the normal boundary between investigation, same-thread operator authorization, and later engineering delivery. It contains no emergency-containment contract, so that remains an open design question rather than a current capability.",[18,560,562],{"id":561},"inspect-the-authority-boundary-not-the-confidence-of-the-conclusion","Inspect the authority boundary, not the confidence of the conclusion",[11,564,565],{},"The next useful test is a future one: can a reviewer find a distinct investigation conclusion, authorization, and delivery record—and, when urgent containment occurs, identify its separate authority without backfilling root-cause certainty into the plan?",{"title":64,"searchDepth":65,"depth":65,"links":567},[568,569,570,571,572],{"id":478,"depth":65,"text":479},{"id":504,"depth":65,"text":505},{"id":517,"depth":65,"text":518},{"id":540,"depth":65,"text":541},{"id":561,"depth":65,"text":562},"A record-based way to keep a persuasive issue diagnosis from silently becoming an unapproved engineering change.",{},"\u002Farticles\u002Fhow-to-separate-issue-investigation-from-implementation","2026-07-28",[578,579],"support-workflow-issue-investigator","support-workflow-delivery-handoff",[581,582,583],"what-ai-agent-handoff-should-include","how-ai-orchestrators-triage-feedback","how-to-build-ai-agent-workflow",[585,586,587],"support-issue-investigation","support-delivery-task-handoff","engineering-tracked-delivery","Learn how to separate issue investigation, operator authorization, and engineering implementation so a plausible diagnosis does not silently become a fix plan",{"title":456,"description":573},"articles\u002Fhow-to-separate-issue-investigation-from-implementation",[592,593,594,595,596],"issue investigation","engineering delivery","operator authorization","support operations","AI workflows","si3gE37YG7COLZTqUK3MjLDhyU-yGLJtgRHD-vAUCPw",{"id":599,"title":600,"author":6,"body":601,"category":70,"description":688,"extension":72,"featured":73,"heroImage":74,"meta":689,"navigation":76,"path":690,"publishedAt":691,"readingTime":189,"relatedAgents":692,"relatedArticles":696,"relatedWorkflows":697,"searchIntent":699,"seo":700,"stem":701,"topics":702,"updatedAt":691,"visual":92,"__hash__":707},"articles\u002Farticles\u002Fhow-ai-agents-should-explain-blockers-to-humans.md","How an AI agent can explain a blocker without assigning the repair",{"type":8,"value":602,"toc":684},[603,606,609,626,630,633,636,651,654,658,661,670,678],[11,604,605],{},"In the observed run, an evidence write stopped because its active-step grant was unavailable. The record named no authorized repair owner. One fact identifies the interrupted action; the other leaves open who, if anyone, can change the state that blocked it.",[11,607,608],{},"For that occurrence, the report can carry both facts without assigning the repair to its recipient.",[413,610,611],{},[11,612,613,617,618,621,622,625],{},[614,615,616],"strong",{},"Blocked:"," The current record shows the evidence write lacks an active-step grant and names no authorized repair owner. If you are authorized to claim ",[469,619,620],{},"research-fact-collection",", claim it; otherwise use an approved route if one exists, or return ownership unresolved. I will retry the write only after the step is actually claimed and ",[469,623,624],{},"resource.upsert"," is observed available.",[18,627,629],{"id":628},"the-condition-is-known-the-owner-is-not","The condition is known; the owner is not",[11,631,632],{},"The first sentence keeps the interruption narrow. The action waiting to run is the evidence write, and the condition attached to it is a missing active-step grant. It makes no assumption about a person's role, permissions, or ability to alter workflow state.",[11,634,635],{},"The middle sentence is the decision request. It offers a conditional action to a recipient who can make the claim. Where an approved route exists, the request can move through it. Otherwise, the recipient can return ownership unresolved. Neither response assigns the repair to the recipient by default.",[11,637,638,639,644,645,650],{},"Microsoft’s ",[304,640,643],{"href":641,"rel":642},"https:\u002F\u002Fwww.microsoft.com\u002Fen-us\u002Fresearch\u002Fwp-content\u002Fuploads\u002F2019\u002F01\u002FGuidelines-for-Human-AI-Interaction-camera-ready.pdf",[308],"Guidelines for Human-AI Interaction"," include explanations of why an AI system behaved as it did and support for correction or recovery. GOV.UK’s ",[304,646,649],{"href":647,"rel":648},"https:\u002F\u002Fdesign-system.service.gov.uk\u002Fcomponents\u002Ferror-message\u002F",[308],"error-message guidance"," asks services to state what happened and how to fix it. In this case, the explanation is the unavailable grant; the next decision is whether the recipient can take the conditional action or route it.",[11,652,653],{},"The message intentionally says nothing about prior research or source notes. The record at hand establishes an unavailable write and a later available grant, rather than the state of earlier material. When retained work is known, it can be named. When the record is silent, the report leaves it silent.",[18,655,657],{"id":656},"a-reply-is-a-signal-state-confirmation-comes-later","A reply is a signal; state confirmation comes later",[11,659,660],{},"“I can claim the step” is an ownership signal. It does not show that the claim has occurred or that the write tool is now available. In this proposed method, the agent inspects the active state before returning to its interrupted action.",[11,662,663,664,666,667,669],{},"One StackOS receipt gives the relevant sequence: before the research step was claimed, ",[469,665,624],{}," was unavailable; after it was claimed, ",[469,668,624],{}," appeared granted in the active-step tool list. The record reaches no farther. It does not identify the repair owner or show the result of a retry.",[11,671,672,677],{},[304,673,676],{"href":674,"rel":675},"https:\u002F\u002Fwww.rfc-editor.org\u002Frfc\u002Frfc9457.html",[308],"RFC 9457"," offers a structural analogy for this handoff point. Its problem-details model separates a problem from occurrence-specific detail and directs detail toward correction rather than debugging information. This proposed report makes an editorial choice to identify the grant state, the conditional decision, and the verification point without expanding into raw payloads, tokens, credential references, private paths, or security-sensitive configuration.",[11,679,680,681,683],{},"The recipient may provide an ownership signal, use an approved route when one exists, or return ownership unresolved; the agent verifies that the step is claimed and ",[469,682,624],{}," is available, then retries the evidence write.",{"title":64,"searchDepth":65,"depth":65,"links":685},[686,687],{"id":628,"depth":65,"text":629},{"id":656,"depth":65,"text":657},"A case-led way to report one recoverable AI agent authority interruption without assuming who can make the repair.",{},"\u002Farticles\u002Fhow-ai-agents-should-explain-blockers-to-humans","2026-07-27",[693,694,695],"branding-narrative-writer","branding-claim-auditor","branding-sanitization-reviewer",[582,192,581],[698,587],"branding-content-production","See how an AI agent can explain one recoverable blocker without assuming who owns the repair",{"title":600,"description":688},"articles\u002Fhow-ai-agents-should-explain-blockers-to-humans",[703,704,705,706],"AI agent blockers","human-AI interaction","workflow recovery","agent authority","GRiEoqs6UAKli53tFsqyUXrU2iGX9DJXcaQb1hHKb1s",{"id":709,"title":710,"author":6,"body":711,"category":70,"description":858,"extension":72,"featured":73,"heroImage":74,"meta":859,"navigation":76,"path":860,"publishedAt":691,"readingTime":189,"relatedAgents":861,"relatedArticles":864,"relatedWorkflows":865,"searchIntent":866,"seo":867,"stem":868,"topics":869,"updatedAt":691,"visual":875,"__hash__":876},"articles\u002Farticles\u002Fhow-to-build-ai-content-workflow-that-does-not-sound-generic.md","Why an AI content workflow can still sound generic",{"type":8,"value":712,"toc":851},[713,716,719,722,725,729,732,735,738,741,745,748,792,795,798,802,805,813,816,819,823,826,829,832,835,838,842,845,848],[11,714,715],{},"We had current workflow guidance and local role files. Specialists returned ready verdicts. Direct reading still found voice and structural drift.",[11,717,718],{},"That receipt changed the decision we made next. We reopened the occurrence-specific briefing and the orchestrator’s adjudication, rather than treating ready as the final answer.",[11,720,721],{},"This is one bounded content-delivery record. It does not show that a revised workflow has solved generic prose or improved any reader, ranking, or detector outcome.",[11,723,724],{},"The question behind “how to build an AI content workflow that does not sound generic” starts here: what did the delivery leave unresolved before the writer began?",[18,726,728],{"id":727},"a-ready-verdict-can-be-locally-true","A ready verdict can be locally true",[11,730,731],{},"A specialist verdict answers the responsibility assigned to that specialist. A claim review can establish whether the draft’s material statements have support. A sanitization review can identify whether public-use boundaries hold. A voice review can return its bounded finding.",[11,733,734],{},"Those results matter. They are still narrower than integrated article quality.",[11,736,737],{},"An integrated article has to carry one accountable argument from its opening through its ending. Its reader needs to understand what was observed, why that observation changes the decision at hand, what evidence bears the weight of the claim, and where the argument stops. A set of completed specialist checks does not automatically settle that relationship.",[11,739,740],{},"That was the contradiction in our delivery. The workflow record contained ready verdicts, while direct prose evidence still showed voice and structural drift. We treated the contradiction as evidence about the process, rather than as a reason to add another layer of wording polish.",[18,742,744],{"id":743},"locate-the-earliest-incomplete-decision","Locate the earliest incomplete decision",[11,746,747],{},"Before editing sentences, inspect the decisions that give an article its center.",[749,750,751,764],"table",{},[752,753,754],"thead",{},[755,756,757,761],"tr",{},[758,759,760],"th",{},"Decision",[758,762,763],{},"What to inspect",[765,766,767,776,784],"tbody",{},[755,768,769,773],{},[770,771,772],"td",{},"Reader job",[770,774,775],{},"Does the article help a defined reader make a real decision, or has the reader been reduced to a topic label?",[755,777,778,781],{},[770,779,780],{},"Evidence owner",[770,782,783],{},"Can the article identify the operator, source, record, or bounded experience that carries its important observation?",[755,785,786,789],{},[770,787,788],{},"Selected thesis",[770,790,791],{},"Does the argument say something this evidence can support, with a consequence for the reader?",[11,793,794],{},"In this case, the evidence owner was a bounded operator receipt: current workflow guidance and local role files existed, specialists returned ready verdicts, and direct reading still found drift. That receipt gave the article an operating problem. The reader job became diagnostic rather than promotional. The working thesis became narrower: a content workflow can pass bounded checks while leaving the integrated article unresolved.",[11,796,797],{},"The table is not a universal content template. These are the earliest decisions that mattered for this occurrence. A different article may need a different starting point.",[18,799,801],{"id":800},"use-canonical-work-as-evidence-about-the-whole-article","Use canonical work as evidence about the whole article",[11,803,804],{},"Direct comparison with live canonical work is useful because it tests the integrated article rather than another workflow output.",[11,806,807,808,812],{},"The closest comparison here is ",[304,809,811],{"href":810},"\u002Flibrary\u002Farticles\u002Fhow-to-build-ai-agent-workflow","How to build an AI agent workflow",". That piece owns a general problem-to-contract argument. If this draft begins by explaining general workflow architecture, the comparison reveals a concrete consequence: its selected thesis or form has become interchangeable with an existing article.",[11,814,815],{},"That finding does not mean the earlier article is a template to avoid word by word. It means the current draft has lost the job that only its operator receipt can do.",[11,817,818],{},"Comparison can expose the same problem later in the piece. A section that replaces the receipt with reusable workflow advice may be structurally competent while no longer advancing this article’s argument. The repair may belong in the selected thesis or form decision, not in a synonym swap.",[18,820,822],{"id":821},"the-orchestrator-has-to-decide-what-the-contradiction-means","The orchestrator has to decide what the contradiction means",[11,824,825],{},"The orchestrator receives specialist findings alongside the draft and its accepted briefing. When direct prose evidence contradicts an aggregate-ready implication, the orchestrator should reject that implication for the current article.",[11,827,828],{},"Its next decision is substantive: return to evidence, angle, or draft form at the earliest incomplete decision.",[11,830,831],{},"A missing accountable observation returns to evidence ownership. An opening that could introduce any AI workflow article returns to the reader job or selected thesis. A draft that has become interchangeable with a canonical comparison returns to form. Sentence editing comes after those decisions remain sound.",[11,833,834],{},"Claim, voice, and sanitization boundaries still matter in this route. They keep the repair from inventing proof, overstating a conclusion, or using a detail that cannot be public. They do not replace the integrated reading that decides whether the article still has one coherent argument.",[11,836,837],{},"A final-paragraph repair should not conceal an upstream problem.",[18,839,841],{"id":840},"preserve-the-question-for-the-next-run","Preserve the question for the next run",[11,843,844],{},"This method is intended for cases where a team has an observation, an evidence owner, a reader decision, and someone who can route a material finding through the workflow.",[11,846,847],{},"The record worth preserving after each material finding is simple: which earliest decision did it require us to reopen?",[11,849,850],{},"Over time, that record may show whether recurring drift starts with evidence selection, reader job, selected thesis, or draft form. Until completed work supports a conclusion, that remains the inspectable question to carry into the next article.",{"title":64,"searchDepth":65,"depth":65,"links":852},[853,854,855,856,857],{"id":727,"depth":65,"text":728},{"id":743,"depth":65,"text":744},{"id":800,"depth":65,"text":801},{"id":821,"depth":65,"text":822},{"id":840,"depth":65,"text":841},"A bounded diagnostic method for tracing voice and structural drift back to the earliest editorial decision that needs reopening.",{},"\u002Farticles\u002Fhow-to-build-ai-content-workflow-that-does-not-sound-generic",[862,693,694,863,695],"branding-channel-strategist","branding-voice-reviewer",[583,582,581],[698],"Diagnose why an AI content workflow can still produce generic-seeming prose and decide which editorial decision to reopen",{"title":710,"description":858},"articles\u002Fhow-to-build-ai-content-workflow-that-does-not-sound-generic",[870,871,872,873,874],"AI content workflow","AI writing","editorial operations","brand voice","content review","roles","Gim64h6yFLMjVRtXbAQ9ett0CCQfEJNttoTzaYpyub0",{"id":878,"title":879,"author":6,"body":880,"category":70,"description":1052,"extension":72,"featured":73,"heroImage":74,"meta":1053,"navigation":76,"path":1054,"publishedAt":691,"readingTime":1055,"relatedAgents":1056,"relatedArticles":1059,"relatedWorkflows":1062,"searchIntent":1064,"seo":1065,"stem":1066,"topics":1067,"updatedAt":691,"visual":92,"__hash__":1072},"articles\u002Farticles\u002Fhow-to-do-keyword-research-for-ai-search.md","How to do keyword research for AI search",{"type":8,"value":881,"toc":1047},[882,889,892,953,957,960,973,981,990,994,997,1000,1003,1006,1010],[11,883,884,885,888],{},"The query “how to do keyword research for AI search” returned ",[469,886,887],{},"null"," for search volume, CPC, and paid competition in our corrected July research batch. The research decision began there. The empty fields left the question active, while the team checked whether the query came from a concrete operating problem and whether the available record could support a useful article.",[11,890,891],{},"The July case was kept as a small ledger instead of compressed into a single volume judgment.",[749,893,894,907],{},[752,895,896],{},[755,897,898,901,904],{},[758,899,900],{},"Record",[758,902,903],{},"What the July case established",[758,905,906],{},"Use in the decision",[765,908,909,920,931,942],{},[755,910,911,914,917],{},[770,912,913],{},"Question origin",[770,915,916],{},"Public workflow jobs, decisions, handoffs, failure modes, and existing material produced 472 exact-new candidates across 15 clusters after deduplication against a 500-keyword baseline.",[770,918,919],{},"The query belonged to a documented problem-first research corpus.",[755,921,922,925,928],{},[770,923,924],{},"Measurement receipt",[770,926,927],{},"A 472-phrase request hit a phrase-length limit; a corrected 448-phrase request completed after 24 over-limit questions were excluded.",[770,929,930],{},"Provider task status and endpoint limits became part of the interpretation.",[755,932,933,936,939],{},[770,934,935],{},"Result snapshots",[770,937,938],{},"Eight selected US\u002Fen snapshots from July 12 each contained an AI Overview; the primary query was outside that sample.",[770,940,941],{},"The snapshots described related observations from that date.",[755,943,944,947,950],{},[770,945,946],{},"Evidence and ownership",[770,948,949],{},"The research ledger preserved the method and the July 25 article corpus was reviewed.",[770,951,952],{},"The question could be assessed as a separate reader job with a named evidence record.",[18,954,956],{"id":955},"what-the-measurement-instrument-actually-returned","What the measurement instrument actually returned",[11,958,959],{},"The first request contained all 472 phrases. At least one question exceeded the endpoint’s 10-word limit, so the provider task failed. The corrected request excluded 24 over-limit questions and returned results for 448 phrases. That sequence made the task-level result part of the evidence because it established whether the measurement completed.",[11,961,962,963,968,969,972],{},"The selected ",[304,964,967],{"href":965,"rel":966},"https:\u002F\u002Fdocs.dataforseo.com\u002Fv3\u002Fkeywords_data-google_ads-search_volume-live\u002F",[308],"DataForSEO Google Ads endpoint"," accepts up to 1,000 phrases, with an 80-character and 10-word limit per phrase. Its documentation also records that Google Ads may return no data for some keyword groups. Within the corrected batch, four phrases had positive returned search volume and 444 had a null ",[469,970,971],{},"search_volume"," field. The primary query also had null CPC and paid-competition fields.",[11,974,975,980],{},[304,976,979],{"href":977,"rel":978},"https:\u002F\u002Fsupport.google.com\u002Fgoogle-ads\u002Fanswer\u002F3022575?hl=en",[308],"Google Ads describes historical keyword metrics"," as rounded observations for a keyword and close variants under the chosen month range, location, and Search Network settings. In this ledger, the result records what that historical Ads measurement supplied for the chosen query and settings. Human need, AI-search value, and future page performance remained unknown.",[11,982,983,984,989],{},"The eight result snapshots formed a separate observation beside that measurement. Each selected July 12 snapshot contained an AI Overview. The primary query was outside the sample, so the record remained specific to the eight selected queries and their date. Google’s ",[304,985,988],{"href":986,"rel":987},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Fappearance\u002Fai-features",[308],"AI features guidance"," says AI Overviews and AI Mode may use query fan-out across related subtopics and data sources. It applies the same SEO fundamentals to AI features and treats eligibility, crawling, indexing, serving, and inclusion as separate outcomes. For this team, that supported inspecting related questions while keeping the sample’s scope visible.",[18,991,993],{"id":992},"the-query-still-needed-an-evidence-owner-and-a-place-in-the-corpus","The query still needed an evidence owner and a place in the corpus",[11,995,996],{},"The keyword batch identified a candidate. The article required a record that could explain the method and a corpus decision about where that explanation belonged.",[11,998,999],{},"For this query, the evidence owner is a dated research ledger: the problem-first expansion, the failed and corrected measurement receipts, the selected result snapshots, and the primary documentation that defines their limits. The StackOS records preserve which request failed, what was excluded, what the corrected response returned, and how the corpus check was resolved. The article uses that provenance to explain the research decision.",[11,1001,1002],{},"The July 25 corpus review found no existing article responsible for this exact reader job. The candidate could therefore remain a separate canonical packet. A different question could land elsewhere: an existing article may already carry the explanation, or the research may lack a source that can substantiate one. Those are content-ownership decisions, separate from the availability of a volume field.",[11,1004,1005],{},"The dated case supports one explanation: problem-first questions can be examined through several bounded signals while null Ads fields remain unknowns. It leaves rankings, inclusion, traffic, conversions, and citation-format outcomes outside the case record.",[18,1007,1009],{"id":1008},"disposition-for-this-candidate","Disposition for this candidate",[749,1011,1012,1021],{},[752,1013,1014],{},[755,1015,1016,1019],{},[758,1017,1018],{},"Status",[758,1020,900],{},[765,1022,1023,1031,1039],{},[755,1024,1025,1028],{},[770,1026,1027],{},"Proceed",[770,1029,1030],{},"Assign a narrow case-led canonical packet. The question has an operating origin, corrected measurement receipts, dated result observations, a named evidence record, and a reader job that was distinct in the July 25 corpus review.",[755,1032,1033,1036],{},[770,1034,1035],{},"Hold",[770,1037,1038],{},"Retain the question in research when attribution or content ownership is incomplete. Further keyword data may refine measurement, while those two decisions require their own evidence.",[755,1040,1041,1044],{},[770,1042,1043],{},"Reject",[770,1045,1046],{},"Reject use of this record for a ranking, inclusion, traffic, conversion, or citation-format conclusion. Those outcomes sit beyond the case and the primary sources.",{"title":64,"searchDepth":65,"depth":65,"links":1048},[1049,1050,1051],{"id":955,"depth":65,"text":956},{"id":992,"depth":65,"text":993},{"id":1008,"depth":65,"text":1009},"A case-led research method for deciding what a natural-language AI-search question can support when conventional keyword fields are missing.",{},"\u002Farticles\u002Fhow-to-do-keyword-research-for-ai-search","7 min read",[1057,1058,862,693],"seo-workflow-keyword-research","branding-evidence-curator",[1060,1061,583],"how-to-build-ai-content-workflow-that-does-not-sound-generic","how-to-use-product-evidence-without-writing-a-product-pitch",[1063,698],"seo-keyword-research","Learn how to research natural-language questions for AI search using problem evidence, conventional keyword data, result inspection, and accountable source records",{"title":879,"description":1052},"articles\u002Fhow-to-do-keyword-research-for-ai-search",[1068,1069,1070,1071],"keyword research","AI search","content research","editorial evidence","uXyCqG02f_wgW2CmkJZUYJZAE4nb7FjgqwVejm4YKUM",{"id":1074,"title":1075,"author":6,"body":1076,"category":70,"description":1210,"extension":72,"featured":73,"heroImage":74,"meta":1211,"navigation":76,"path":1212,"publishedAt":691,"readingTime":1055,"relatedAgents":1213,"relatedArticles":1214,"relatedWorkflows":1216,"searchIntent":1217,"seo":1218,"stem":1219,"topics":1220,"updatedAt":691,"visual":92,"__hash__":1225},"articles\u002Farticles\u002Fhow-to-use-product-evidence-without-writing-a-product-pitch.md","How to use product evidence without writing a product pitch",{"type":8,"value":1077,"toc":1203},[1078,1081,1084,1087,1091,1094,1097,1100,1103,1107,1110,1113,1116,1119,1124,1127,1130,1134,1137,1142,1145,1148,1156,1165,1169,1172,1175,1178,1181,1185,1188,1191,1194,1197,1200],[11,1079,1080],{},"One recent StackOS change left three useful records behind. A focused test named missing behavior in an interactive connection flow. Repository-bound checks later covered the implemented path. The live in-app click-through remained unperformed because the required browser backend was unavailable.",[11,1082,1083],{},"A broad line such as “the connection experience is seamless” would compress those records into a benefit the evidence does not establish. The more useful article question is: what can a reader responsibly conclude from this bundle?",[11,1085,1086],{},"Use product evidence by carrying the observed change, verification scope, unexercised path, and reader consequence together. The product remains a concrete receipt. The reader gets a decision that can travel beyond it.",[18,1088,1090],{"id":1089},"a-product-receipt-is-not-a-reader-decision","A product receipt is not a reader decision",[11,1092,1093],{},"A receipt records something that happened or was checked. An article has to explain why that record matters, where it stops, and what someone can do with it.",[11,1095,1096],{},"Consider an article about a newly implemented connection flow. A release note can name the behavior that changed. A product page can describe the behavior available now. An operator reading either one may still need to know how much of the claim was verified and what remains unproven.",[11,1098,1099],{},"That question gives the evidence its role in the article. The product supplies a case the reader can inspect. The article supplies the reasoning that turns the case into a useful decision.",[11,1101,1102],{},"Detailed feature copy can be accurate while leaving that job undone. If the reader cannot carry away a way to evaluate another claim, the piece has mainly documented the product for itself.",[18,1104,1106],{"id":1105},"work-one-receipt-through-to-its-boundary","Work one receipt through to its boundary",[11,1108,1109],{},"The first StackOS record was a focused red test. It exposed missing behavior in the interactive connection path: the flow lacked a clear Connect action, did not persist the relevant setup before authorization began, and did not handle the returned state consistently. That receipt establishes the earlier gap. It does not describe a customer incident or every part of account setup.",[11,1111,1112],{},"The later repository-bound verification covered the implemented behavior. The current path presents one Connect action, validates and stores the required application fields, starts authorization, handles the returned outcome, and clears the callback state after reading it. That supports a specific implementation claim within the environment the checks exercised.",[11,1114,1115],{},"A third record keeps the claim at its proper size. The live in-app click-through was not run in that delivery because the required browser backend was unavailable. Repository checks passed; the live interaction remained a separate proof obligation.",[11,1117,1118],{},"Together, these records support a sentence such as:",[413,1120,1121],{},[11,1122,1123],{},"Repository-bound verification covered the implemented connection and callback behavior. The live in-app path remained unexercised in that delivery.",[11,1125,1126],{},"The sentence is less expansive than a benefit label. It is also more useful. A reader can see what changed, which proof exists, and why “fully verified” or “seamless” would outrun it.",[11,1128,1129],{},"This is the transferable decision: name the environment that produced the evidence, then keep the claim inside it. A test result, demo, release receipt, and production observation can each support different statements. None silently stands in for the others.",[18,1131,1133],{"id":1132},"write-the-reader-decision-before-selecting-product-details","Write the reader decision before selecting product details",[11,1135,1136],{},"Start with one working sentence:",[413,1138,1139],{},[11,1140,1141],{},"After reading, the reader should be able to ______ because this receipt shows ______, while ______ remains unverified.",[11,1143,1144],{},"For this example, the reader should be able to judge the strength of an implementation claim. The red test belongs because it defines the change. The repository-bound verification belongs because it defines the current support. The unexercised live path belongs because it prevents a wider interpretation.",[11,1146,1147],{},"Other product details may be true and still be unnecessary. If a detail does not change the reader’s decision, it pulls the article toward a feature tour.",[11,1149,1150,1155],{},[304,1151,1154],{"href":1152,"rel":1153},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Ffundamentals\u002Fcreating-helpful-content",[308],"Google’s people-first content guidance"," provides a useful editorial boundary. It asks whether content adds original information or analysis, demonstrates relevant first-hand expertise, serves an intended audience, and helps someone achieve a goal. Those questions do not predict how this article will rank. They do clarify why a catalogue of product facts is weaker than a documented case that teaches a usable distinction.",[11,1157,1158,1159,1164],{},"The ",[304,1160,1163],{"href":1161,"rel":1162},"https:\u002F\u002Fwww.ftc.gov\u002Flegal-library\u002Fbrowse\u002Fftc-policy-statement-regarding-advertising-substantiation",[308],"FTC’s advertising-substantiation policy"," sets another boundary for objective product claims: express and implied claims need a reasonable basis before dissemination, and the wording should not imply more support than the advertiser possesses. This is a general U.S. advertising principle, not tailored legal advice or an endorsement of StackOS. It matters here because phrases such as “tests show” and “verified” can communicate a broader evidence scope than the underlying work provides.",[18,1166,1168],{"id":1167},"remove-the-product-name-and-inspect-what-remains","Remove the product name and inspect what remains",[11,1170,1171],{},"Take the working paragraph and temporarily remove the company and feature names. The concrete mechanism should still leave the reader with a decision rule.",[11,1173,1174],{},"In this case, the rule survives: distinguish the earlier gap, the behavior covered by verification, and the live path that was not exercised. A team can use that rule when writing its own release note, evaluating a vendor claim, or deciding whether an internal result is ready for a public article.",[11,1176,1177],{},"This is a scratch test, not an instruction to anonymize the final piece. The StackOS receipt stays because it keeps the advice accountable and specific. Removing the name briefly reveals whether the receipt is explaining the lesson or merely asking the reader to notice the product.",[11,1179,1180],{},"The same test exposes a missing thesis. If nothing remains after the name disappears, decide which job the content actually has. It may be a product update, documentation, or a landing page. Those forms can be useful. They should not borrow the authority of an evidence-led article when no independent reader decision exists.",[18,1182,1184],{"id":1183},"stop-when-the-evidence-cannot-carry-the-proposed-claim","Stop when the evidence cannot carry the proposed claim",[11,1186,1187],{},"Some product work should not become an article yet.",[11,1189,1190],{},"Hold the piece when the intended conclusion depends on customer reaction, adoption, conversion, satisfaction, reliability, or ranking evidence that has not been observed. Hold it when a central live path remains untested and the article cannot preserve that boundary without losing its premise. Hold it when the only supported statement is that a feature exists.",[11,1192,1193],{},"The next action may be to collect a live receipt, narrow the claim, write a release note, or leave the idea parked. More copy cannot repair missing evidence.",[11,1195,1196],{},"A smaller article can still be worth keeping when its bounded receipt gives the reader a decision they can use now. The receipt, limit, and conclusion need to remain connected all the way through the draft.",[11,1198,1199],{},"For this piece, the publication decision is to retain the verification boundary. The product example stays because it makes evidence scope visible. It does not become a claim about ease, safety, reliability, or user response.",[11,1201,1202],{},"That is the edge this evidence supports: use the product receipt to help the reader judge a claim, and stop the claim where the receipt stops.",{"title":64,"searchDepth":65,"depth":65,"links":1204},[1205,1206,1207,1208,1209],{"id":1089,"depth":65,"text":1090},{"id":1105,"depth":65,"text":1106},{"id":1132,"depth":65,"text":1133},{"id":1167,"depth":65,"text":1168},{"id":1183,"depth":65,"text":1184},"Turn a bounded product receipt into a useful reader decision without claiming more than the evidence establishes.",{},"\u002Farticles\u002Fhow-to-use-product-evidence-without-writing-a-product-pitch",[1058,862,693,694,863,695],[1060,583,1215],"how-ai-agents-use-accounts-safely",[698],"Decide how to use bounded product evidence in an article without turning the product itself into the thesis",{"title":1075,"description":1210},"articles\u002Fhow-to-use-product-evidence-without-writing-a-product-pitch",[1221,1222,872,1223,1224],"product evidence","content substantiation","AI content fact checking","reader-first content","lBu9hbdV8CAtjjTEUE6NT3TS6WqULNvD59EcsoFmIKU",{"id":1227,"title":1228,"author":6,"body":1229,"category":70,"description":1512,"extension":72,"featured":76,"heroImage":74,"meta":1513,"navigation":76,"path":1514,"publishedAt":1515,"readingTime":1516,"relatedAgents":1517,"relatedArticles":1518,"relatedWorkflows":1519,"searchIntent":1520,"seo":1521,"stem":1522,"topics":1523,"updatedAt":1515,"visual":1241,"__hash__":1527},"articles\u002Farticles\u002Fai-workflow-automation.md","AI workflow automation: automate the rules, not the judgment",{"type":8,"value":1230,"toc":1504},[1231,1234,1237,1243,1247,1250,1253,1256,1259,1262,1265,1269,1287,1290,1293,1313,1316,1320,1323,1326,1329,1332,1335,1342,1346,1349,1352,1444,1447,1450,1454,1457,1460,1463,1470,1474,1477,1495,1498,1501],[11,1232,1233],{},"AI workflow automation combines two different kinds of control. Code should enforce the rules that must hold every time: state, dependencies, permissions, schemas, receipts, and stopping conditions. An agent should decide what cannot be known until the work is underway: which evidence matters, whether the plan should adapt, and which feedback belongs in the result.",[11,1235,1236],{},"Treating the whole workflow as either a fixed automation or an autonomous agent misses the useful middle. The practical design question is not, “How much AI can we add?” It is, “Which decisions should still require judgment?”",[1238,1239],"article-concept-visual",{"caption":1240,"mode":1241,"title":1242},"The runtime enforces invariants. Agents make evidence-dependent decisions. People enter for missing intent or consequential choices.","connections","One workflow, three kinds of control",[18,1244,1246],{"id":1245},"a-failure-that-a-better-prompt-could-not-fix","A failure that a better prompt could not fix",[11,1248,1249],{},"We ran into a useful example while refining our own content workflow.",[11,1251,1252],{},"The workflow definition had changed, but part of the running system still held an older generation of the plugin and resource contracts. The agent could see the current content workflow while receiving an older schema for the record it needed to write. One part of the system described the right job; another enforced the wrong shape.",[11,1254,1255],{},"There was a second gap. Each workflow step already declared an output contract, but a step could still be recorded as successful without proving that its result matched that contract.",[11,1257,1258],{},"Neither problem belonged in the prompt. Telling the agent to “use the latest schema” would not make two runtime generations consistent. Telling it to “return every required field” would not make success verifiable.",[11,1260,1261],{},"We moved both responsibilities into the mechanical layer. Editable plugin manifests now carry a source-generation fingerprint, and the catalog resynchronizes when that generation changes. Successful step results are validated against their frozen JSON Schema before any lifecycle transition is persisted. If a required field is missing, the step remains running and the error points to the exact field that needs repair.",[11,1263,1264],{},"We then exercised the failure path live: an incomplete result was rejected without advancing the step, and the corrected result completed it. This is bounded first-party evidence from one implementation, not proof that the same architecture fits every system. The lesson is narrower: if correctness depends on an invariant, the system should enforce it without asking the model to remember.",[18,1266,1268],{"id":1267},"put-stable-rules-in-the-mechanical-layer","Put stable rules in the mechanical layer",[11,1270,1271,1275,1276,1280,1281,1286],{},[304,1272,1274],{"href":306,"rel":1273},[308],"Anthropic distinguishes workflows from agents"," by who controls the path: workflows use predefined code paths, while agents dynamically direct their process and tool use. Microsoft’s ",[304,1277,1279],{"href":313,"rel":1278},[308],"orchestration pattern guidance"," and Google Cloud’s ",[304,1282,1285],{"href":1283,"rel":1284},"https:\u002F\u002Fdocs.cloud.google.com\u002Farchitecture\u002Fchoose-design-pattern-agentic-ai-system",[308],"agentic design-pattern guide"," make a similar distinction between predictable sequences and dynamic orchestration.",[11,1288,1289],{},"That distinction is useful inside one workflow, not only when choosing an architecture for the whole system.",[11,1291,1292],{},"The mechanical layer should own conditions whose answer does not improve with another model call:",[133,1294,1295,1298,1301,1304,1307,1310],{},[136,1296,1297],{},"A dependent step cannot start before its prerequisite finishes.",[136,1299,1300],{},"A research step can read sources but cannot publish.",[136,1302,1303],{},"A successful result must contain the fields and types its consumer expects.",[136,1305,1306],{},"A completed external action needs a receipt the workflow can inspect before retrying.",[136,1308,1309],{},"A packet-only request must stop before publication.",[136,1311,1312],{},"The current state and evidence refs must survive the conversation that produced them.",[11,1314,1315],{},"These controls reduce ambiguity without reducing useful autonomy. The agent no longer spends judgment on whether a required field is optional this time or whether “packet only” might permit a deployment. It can use that judgment on the work itself.",[18,1317,1319],{"id":1318},"keep-evidence-dependent-choices-with-the-agent","Keep evidence-dependent choices with the agent",[11,1321,1322],{},"Some decisions look repetitive but do not have a stable answer.",[11,1324,1325],{},"In this article’s workflow, the interview step was always present, but the interview was not mandatory. The agent had to inspect the current voice guide, prior pieces, recorded operator statements, and the new topic. Those sources already captured the relevant judgment, so the interview was skipped with a reason and a list of perspectives the article could not claim.",[11,1327,1328],{},"Hard-coding “always interview” would add ceremony. Hard-coding “never interview” would remove a source when first-hand experience was actually missing. The stable rule is that the decision must be made and explained. The answer remains contextual.",[11,1330,1331],{},"The same boundary applies to research and review. A schema can require a source ledger; it cannot decide which source resolves a contradiction. A workflow can require independent claim and voice review; it should not automatically turn every reviewer preference into another delivery cycle.",[11,1333,1334],{},"The orchestrator owns that gate. It can accept a supported blocker, send a specific defect back for repair, retain a preference as advice, and reject an unsupported or out-of-scope finding. Review produces evidence. It does not acquire authority over the original goal merely because it happened later.",[11,1336,1337,1338,1341],{},"This is where an ",[304,1339,1340],{"href":810},"AI agent workflow"," differs from a long automation script. The contract defines the operating boundary. Reasoning handles the parts whose answer depends on meaning, evidence, or changed conditions.",[18,1343,1345],{"id":1344},"one-workflow-can-mix-all-three-control-modes","One workflow can mix all three control modes",[11,1347,1348],{},"Our content workflow follows a visible sequence: decide on interview scope, collect evidence, choose an angle, draft, review claims and voice, check disclosure risk, render the selected channel packet, preserve the final record, and stop or publish according to the request.",[11,1350,1351],{},"The sequence and handoffs are deterministic. The work inside them is not.",[749,1353,1354,1367],{},[752,1355,1356],{},[755,1357,1358,1361,1364],{},[758,1359,1360],{},"Responsibility",[758,1362,1363],{},"Best owner",[758,1365,1366],{},"Why",[765,1368,1369,1380,1391,1402,1412,1423,1433],{},[755,1370,1371,1374,1377],{},[770,1372,1373],{},"Require a source ledger and claim map",[770,1375,1376],{},"Runtime contract",[770,1378,1379],{},"The requirement is stable and machine-checkable.",[755,1381,1382,1385,1388],{},[770,1383,1384],{},"Decide whether existing evidence is sufficient",[770,1386,1387],{},"Agent",[770,1389,1390],{},"The answer depends on the topic, source quality, and claims being considered.",[755,1392,1393,1396,1399],{},[770,1394,1395],{},"Prevent drafting before research completes",[770,1397,1398],{},"Workflow state",[770,1400,1401],{},"The dependency should hold on every run.",[755,1403,1404,1407,1409],{},[770,1405,1406],{},"Choose the article angle",[770,1408,1387],{},[770,1410,1411],{},"Reader value and evidence fit require interpretation.",[755,1413,1414,1417,1420],{},[770,1415,1416],{},"Decide whether a review finding changes delivery",[770,1418,1419],{},"Orchestrator",[770,1421,1422],{},"The finding must be tested against the accepted goal and evidence.",[755,1424,1425,1428,1430],{},[770,1426,1427],{},"Prevent a packet-only run from publishing",[770,1429,1376],{},[770,1431,1432],{},"Execution intent is an explicit boundary, not a suggestion.",[755,1434,1435,1438,1441],{},[770,1436,1437],{},"Clarify a missing destination or sensitive disclosure choice",[770,1439,1440],{},"Person",[770,1442,1443],{},"Guessing would materially change the requested action or public boundary.",[11,1445,1446],{},"The person is not a rubber stamp between every row. Human participation belongs where the system lacks legitimate authority or information: the goal is ambiguous, evidence conflicts on a consequential point, disclosure ownership is unclear, or an external action needs a choice that was never supplied.",[11,1448,1449],{},"That is different from inserting approval because AI is involved. A mandatory checkpoint can be appropriate for a risky action. It is not a substitute for a clear workflow.",[18,1451,1453],{"id":1452},"use-failure-location-to-improve-the-boundary","Use failure location to improve the boundary",[11,1455,1456],{},"When an AI workflow fails, ask which layer was forced to compensate.",[11,1458,1459],{},"If the agent searched for a source the workflow already knew, context selection failed. If it guessed which account or destination to use, authority was unresolved. If it returned a malformed packet and the system accepted it, validation failed. If a reviewer’s optional rewrite expanded the task, feedback adjudication failed. If the system stopped on missing operator intent and asked one focused question, the boundary may have worked exactly as intended.",[11,1461,1462],{},"This makes ordinary friction useful evidence. A workflow does not need to eliminate every search, retry, or clarification. It needs to keep recovery local and prevent that friction from turning into silent drift.",[11,1464,1158,1465,1469],{},[304,1466,1468],{"href":1467},"\u002Flibrary\u002Farticles\u002Fai-agent-experience","agent experience"," article develops that point at the claimed-step level. The automation boundary is the system-level version: decide which uncertainty the agent should resolve and which uncertainty the system should remove before the step begins.",[18,1471,1473],{"id":1472},"a-compact-automation-boundary-test","A compact automation-boundary test",[11,1475,1476],{},"For each responsibility in a workflow, ask:",[1478,1479,1480,1483,1486,1489,1492],"ol",{},[136,1481,1482],{},"Does the rule need to hold on every valid run?",[136,1484,1485],{},"Can the result be checked without interpreting meaning?",[136,1487,1488],{},"Does the answer change with evidence or intermediate results?",[136,1490,1491],{},"Would a wrong guess change scope, expose data, spend money, or create an external side effect?",[136,1493,1494],{},"Can a failed attempt be repaired locally without replaying completed work?",[11,1496,1497],{},"Stable and machine-checkable responsibilities belong in code, schemas, state transitions, or scoped tool grants. Evidence-dependent responsibilities belong with a reasoning agent. Missing authority or a genuinely consequential choice belongs with the person who owns it.",[11,1499,1500],{},"The boundary will not be perfect on the first run. Ours was not. The useful signal was that a live failure identified two invariants the runtime had left to convention. We fixed those invariants mechanically and kept the editorial decisions with the agents.",[11,1502,1503],{},"That is the point of AI workflow automation: not to automate judgment away, but to stop wasting it on rules the system can already know.",{"title":64,"searchDepth":65,"depth":65,"links":1505},[1506,1507,1508,1509,1510,1511],{"id":1245,"depth":65,"text":1246},{"id":1267,"depth":65,"text":1268},{"id":1318,"depth":65,"text":1319},{"id":1344,"depth":65,"text":1345},{"id":1452,"depth":65,"text":1453},{"id":1472,"depth":65,"text":1473},"A practical way to decide what AI workflows should enforce in code, what agents should decide at runtime, and when a person genuinely needs to step in.",{},"\u002Farticles\u002Fai-workflow-automation","2026-07-12","8 min read",[862,693,694],[583,192,193],[698,587],"Learn how to automate AI workflows without hard-coding the judgment they need",{"title":1228,"description":1512},"articles\u002Fai-workflow-automation",[1524,1525,1526],"AI workflow automation","agent orchestration","workflow architecture","ivj4k_-yJoUYW08VqRr6mbUEC2lYzjoWMWbJCgOnxvo",{"id":1529,"title":1530,"author":6,"body":1531,"category":70,"description":1830,"extension":72,"featured":76,"heroImage":74,"meta":1831,"navigation":76,"path":1832,"publishedAt":1515,"readingTime":1516,"relatedAgents":1833,"relatedArticles":1835,"relatedWorkflows":1837,"searchIntent":1838,"seo":1839,"stem":1840,"topics":1841,"updatedAt":1515,"visual":875,"__hash__":1844},"articles\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback.md","How should an AI orchestrator triage feedback?",{"type":8,"value":1532,"toc":1821},[1533,1536,1539,1543,1546,1549,1552,1555,1567,1571,1574,1577,1597,1600,1603,1606,1610,1613,1674,1677,1680,1684,1687,1725,1728,1737,1740,1744,1747,1750,1753,1760,1763,1767,1770,1773,1776,1779,1783,1786,1789,1812,1815],[11,1534,1535],{},"An AI orchestrator should treat reviewer feedback as evidence, not as an instruction. Its job is to test each finding against the accepted goal, evidence, constraints, and terminal condition, then classify it as a blocker, a repair, a preference, or out of scope. Only findings that protect the agreed outcome should enter delivery.",[11,1537,1538],{},"That gate does not weaken review. It gives review a boundary. Without one, a capable reviewer can always imagine another improvement, and a workflow that accepts every suggestion can keep moving without getting closer to done.",[18,1540,1542],{"id":1541},"why-reviewer-output-is-not-automatically-work","Why reviewer output is not automatically work",[11,1544,1545],{},"A reviewer has a deliberately narrow responsibility. A claim auditor looks for unsupported claims. A security reviewer looks for unsafe behavior. An editor looks for structural and voice problems. That narrowness makes the review useful, but it does not give the reviewer ownership of the whole plan.",[11,1547,1548],{},"The orchestrator has the wider view. It knows what the operator asked for, which constraints were accepted, what evidence is available, which changes have already been made, and what state counts as complete. It should consider a reviewer’s finding from that position.",[11,1550,1551],{},"We learned this while refining our own workflows. Independent reviews surfaced plausible improvements, and it was tempting to treat each one as a new requirement. The result was scope drift: work expanded beyond the plan we had agreed to finish. The individual suggestions were not necessarily bad. The failure was allowing the act of suggesting something to redefine delivery.",[11,1553,1554],{},"The correction was not to remove reviewers or make their instructions weaker. It was to make one responsibility explicit: reviewers report findings; the orchestrator decides which findings belong in the current delivery.",[11,1556,1557,1561,1562,1566],{},[304,1558,1560],{"href":306,"rel":1559},[308],"Anthropic’s evaluator-optimizer pattern"," makes evaluation criteria a condition for a useful review loop. Microsoft’s ",[304,1563,1565],{"href":313,"rel":1564},[308],"maker-checker guidance"," similarly calls for clear acceptance criteria, an iteration cap, and defined fallback behavior. A review loop is controlled by criteria and a stopping rule, not by the mere existence of more feedback.",[18,1568,1570],{"id":1569},"start-with-an-accepted-plan","Start with an accepted plan",[11,1572,1573],{},"Feedback cannot be triaged against a vague intention such as “make it better.” The orchestrator needs a small accepted plan that remains stable while the work is underway.",[11,1575,1576],{},"At minimum, that plan should name:",[133,1578,1579,1582,1585,1588,1591,1594],{},[136,1580,1581],{},"the problem being solved;",[136,1583,1584],{},"the requested output and its scope;",[136,1586,1587],{},"the evidence and constraints that apply;",[136,1589,1590],{},"the acceptance criteria;",[136,1592,1593],{},"the terminal condition;",[136,1595,1596],{},"any decisions reserved for the operator.",[11,1598,1599],{},"This is not a demand for a long specification. A compact plan is often better because the orchestrator can apply it consistently. The important part is that a reviewer finding must point to something in that plan if it is going to change delivery.",[11,1601,1602],{},"Suppose the accepted outcome is a public article with supported material claims, the required sections, the current brand voice, and no sensitive internal details. “A material claim has no source” threatens an acceptance criterion. “The introduction would be more dramatic as a personal story” may be a reasonable editorial preference, but it does not necessarily threaten the outcome.",[11,1604,1605],{},"The orchestrator should not pretend those findings have equal weight.",[18,1607,1609],{"id":1608},"use-four-feedback-classes","Use four feedback classes",[11,1611,1612],{},"The following classification is a practical operating model, not an industry standard. Its value is that every category has a different consequence.",[749,1614,1615,1628],{},[752,1616,1617],{},[755,1618,1619,1622,1625],{},[758,1620,1621],{},"Class",[758,1623,1624],{},"What it means",[758,1626,1627],{},"Orchestrator action",[765,1629,1630,1641,1652,1663],{},[755,1631,1632,1635,1638],{},[770,1633,1634],{},"Blocker",[770,1636,1637],{},"The output cannot meet an accepted criterion, is materially false or unsafe, or violates a hard constraint.",[770,1639,1640],{},"Admit it into delivery and prevent completion until it is resolved or explicitly marked unresolved.",[755,1642,1643,1646,1649],{},[770,1644,1645],{},"Repair",[770,1647,1648],{},"A bounded correction is needed inside the agreed scope.",[770,1650,1651],{},"Route it to the responsible agent with the failed criterion and expected evidence.",[755,1653,1654,1657,1660],{},[770,1655,1656],{},"Preference",[770,1658,1659],{},"The suggestion is defensible, but the current output can meet the accepted outcome without it.",[770,1661,1662],{},"Record it if useful; do not reopen delivery by default.",[755,1664,1665,1668,1671],{},[770,1666,1667],{},"Out of scope",[770,1669,1670],{},"The suggestion changes the goal, adds a new capability, or introduces work not required by the accepted plan.",[770,1672,1673],{},"Reject it for this run or return it as a separate proposal. Do not create follow-up work automatically.",[11,1675,1676],{},"The distinction between a blocker and a repair is useful. A blocker describes the state of the output. A repair describes bounded work that may remove the blocker. Keeping them separate prevents a reviewer from prescribing a large solution when a smaller correction would satisfy the criterion.",[11,1678,1679],{},"Preferences also deserve an explicit category. Otherwise they tend to masquerade as defects. A preference can still be valuable, but “valuable” is not the same as “required now.”",[18,1681,1683],{"id":1682},"make-the-triage-decision-inspectable","Make the triage decision inspectable",[11,1685,1686],{},"The orchestrator does not need a complicated scoring system. It needs a repeatable sequence that exposes why a finding was accepted or rejected.",[1478,1688,1689,1695,1701,1707,1713,1719],{},[136,1690,1691,1694],{},[614,1692,1693],{},"Restate the finding as a testable claim."," Replace “this section is weak” with the specific condition the reviewer believes has failed.",[136,1696,1697,1700],{},[614,1698,1699],{},"Identify the affected criterion."," Ask which accepted requirement, constraint, or terminal condition is threatened.",[136,1702,1703,1706],{},[614,1704,1705],{},"Check the evidence."," Confirm that the finding refers to the current output and has enough evidence to justify action.",[136,1708,1709,1712],{},[614,1710,1711],{},"Classify the finding."," Choose blocker, repair, preference, or out of scope.",[136,1714,1715,1718],{},[614,1716,1717],{},"Choose the smallest valid action."," Admit a blocker, route a repair, record a preference, or reject scope expansion.",[136,1720,1721,1724],{},[614,1722,1723],{},"Re-evaluate completion."," Decide whether the terminal condition is still unmet after the admitted findings are considered.",[11,1726,1727],{},"A useful finding record can stay compact:",[1729,1730,1735],"pre",{"className":1731,"code":1733,"language":1734,"meta":64},[1732],"language-yaml","finding: \"Two factual claims have no source\"\ncriterion: \"Material claims are supported or marked unresolved\"\nevidence: [\"paragraph-6\", \"paragraph-9\"]\nclassification: blocker\naction: \"Return to the writer for a bounded evidence repair\"\nstatus: admitted\n","yaml",[469,1736,1733],{"__ignoreMap":64},[11,1738,1739],{},"The important field is not a severity score. It is the connection between the finding and the accepted plan.",[18,1741,1743],{"id":1742},"keep-judgment-with-the-orchestrator-and-invariants-in-code","Keep judgment with the orchestrator and invariants in code",[11,1745,1746],{},"Feedback triage contains both mechanical and judgment-dependent work.",[11,1748,1749],{},"Code can require every finding to contain a criterion, evidence reference, classification, and status. It can prevent a dependent step from starting while an admitted blocker remains open. It can enforce an iteration limit and preserve the decision record.",[11,1751,1752],{},"Code cannot reliably decide whether a new suggestion protects the operator’s goal or quietly replaces it. That depends on the current evidence, tradeoffs, and intent. The orchestrator should make that judgment.",[11,1754,1755,1756,1759],{},"This follows the same boundary described in ",[304,1757,1524],{"href":1758},"\u002Flibrary\u002Farticles\u002Fai-workflow-automation",": enforce stable rules mechanically, but leave evidence-dependent choices with the agent responsible for the plan.",[11,1761,1762],{},"The reviewers should also remain independent. The writer should not silently grade its own claims, and the orchestrator should not rewrite findings to make them easier to dismiss. Specialists report what they observe. The orchestrator owns admission into delivery.",[18,1764,1766],{"id":1765},"do-not-turn-every-disagreement-into-human-approval","Do not turn every disagreement into human approval",[11,1768,1769],{},"Human input is useful when the workflow lacks something only the operator can supply: intent, authority, a disclosure decision, acceptance of consequential risk, or a real change in scope.",[11,1771,1772],{},"It is not necessary merely because two agents disagree. If the accepted plan already resolves the disagreement, the orchestrator should apply it. Requiring a person to approve every classification would move the gate without improving the decision.",[11,1774,1775],{},"Microsoft’s orchestration guidance distinguishes feedback that loops work back for refinement from approval that advances a workflow. That distinction matters. A content preference is not an authorization decision. A sensitive external action may be.",[11,1777,1778],{},"When a finding would materially change the accepted plan, the orchestrator should stop and present the choice rather than assume permission. That is not routine review. It is a new operator decision.",[18,1780,1782],{"id":1781},"stop-when-the-accepted-outcome-is-reached","Stop when the accepted outcome is reached",[11,1784,1785],{},"A workflow should finish when its terminal condition is true and no admitted blocker remains open. It should not wait until reviewers have no further ideas.",[11,1787,1788],{},"This gives the orchestrator a concrete stopping test:",[133,1790,1791,1794,1797,1800,1803,1806,1809],{},[136,1792,1793],{},"required output exists;",[136,1795,1796],{},"acceptance criteria pass;",[136,1798,1799],{},"material claims have evidence or an explicit unresolved status;",[136,1801,1802],{},"admitted blockers are repaired or deliberately escalated;",[136,1804,1805],{},"required safety and sanitization checks pass;",[136,1807,1808],{},"preferences and out-of-scope suggestions are not blocking delivery;",[136,1810,1811],{},"the iteration limit has not been exceeded.",[11,1813,1814],{},"If the iteration limit is reached with a blocker still open, the workflow should return the best preserved state, the failed criterion, and the next safe action. It should not hide the problem behind another review round.",[11,1816,1817,1818,1820],{},"The broader lesson is simple: feedback improves a workflow only when someone owns the decision to use it. In an ",[304,1819,1340],{"href":810},", that owner is the orchestrator. Reviewers protect specific quality boundaries. The orchestrator protects the agreed outcome.",{"title":64,"searchDepth":65,"depth":65,"links":1822},[1823,1824,1825,1826,1827,1828,1829],{"id":1541,"depth":65,"text":1542},{"id":1569,"depth":65,"text":1570},{"id":1608,"depth":65,"text":1609},{"id":1682,"depth":65,"text":1683},{"id":1742,"depth":65,"text":1743},{"id":1765,"depth":65,"text":1766},{"id":1781,"depth":65,"text":1782},"A practical way for AI orchestrators to separate blocking findings from repairs, preferences, and scope drift without weakening review.",{},"\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback",[694,863,1834],"stackos-sdlc-delivery-reviewer",[583,192,1836],"ai-workflow-automation",[698,587],"Learn how an AI orchestrator should evaluate reviewer feedback without allowing scope drift",{"title":1530,"description":1830},"articles\u002Fhow-ai-orchestrators-triage-feedback",[1842,1843,1525],"AI orchestrators","feedback triage","vwBUM6rx6i9AMg70ZNLkpa9fQOiVO5hbzGXf4zkZWG4",{"id":1846,"title":1847,"author":6,"body":1848,"category":70,"description":2520,"extension":72,"featured":76,"heroImage":74,"meta":2521,"navigation":76,"path":2522,"publishedAt":1515,"readingTime":2523,"relatedAgents":2524,"relatedArticles":2525,"relatedWorkflows":2526,"searchIntent":2527,"seo":2528,"stem":2529,"topics":2530,"updatedAt":1515,"visual":2534,"__hash__":2535},"articles\u002Farticles\u002Fhow-to-refine-ai-agent-workflow.md","How to refine an AI agent workflow: best practices after the first working version",{"type":8,"value":1849,"toc":2508},[1850,1853,1856,1859,1863,1866,1873,1876,1879,1882,1886,1889,1907,1910,1913,1916,1920,1923,1926,1929,1937,1940,1943,1946,1966,1969,1973,1976,1979,2005,2008,2011,2014,2017,2023,2026,2035,2038,2042,2045,2116,2119,2192,2200,2203,2206,2210,2213,2306,2309,2312,2315,2319,2322,2325,2339,2342,2345,2349,2352,2355,2358,2378,2381,2384,2388,2391,2469,2473,2476,2479,2505],[11,1851,1852],{},"To refine an AI agent workflow, I do not start by personally reviewing every step. I ask an agent to manage the refinement. That agent sends subagents through the workflow as first-time operators, collects their firsthand feedback, and questions them after each run about friction, decisions, missing context, and workarounds.",[11,1854,1855],{},"The orchestrator then gates that feedback. It separates consequential defects from normal agent friction, traces accepted findings to the correct layer, and proposes the smallest reusable fix. After the change, fresh agents run the workflow again. We stop when they can reach the accepted outcome reliably—not when nobody can imagine another improvement.",[11,1857,1858],{},"This combines two kinds of evidence: what the workflow produced and what the agents experienced while producing it. The second is easy to miss when the operator becomes the only reviewer.",[18,1860,1862],{"id":1861},"refinement-starts-after-the-workflow-works","Refinement starts after the workflow works",[11,1864,1865],{},"Design and refinement solve different problems.",[11,1867,1868,1869,1872],{},"When we ",[304,1870,1871],{"href":810},"define an AI agent workflow",", we start with the problem, the desired outcome, the orchestration model, the specialist responsibilities, and the terminal condition. The first useful milestone is a workflow that can complete a representative task.",[11,1874,1875],{},"Refinement begins after that milestone. The question is no longer, “What workflow should we build?” It is, “What did agents actually experience when they used it, and which changes would make the accepted outcome more reliable?”",[11,1877,1878],{},"Keeping that boundary explicit prevents a common mistake: redesigning the workflow before understanding the failure. A weak result may come from an ambiguous acceptance criterion, missing context, a poor tool interface, a stale runtime contract, a specialist mistake, or a temporary environment problem. Those causes do not call for the same fix.",[11,1880,1881],{},"More agents can generate more evidence, but more agents, review rounds, and instructions are not themselves proof of a better workflow. Their value is in giving the refinement orchestrator independent runs to compare.",[18,1883,1885],{"id":1884},"preserve-the-accepted-baseline","Preserve the accepted baseline",[11,1887,1888],{},"Before changing anything, write down the state you are trying to preserve. At minimum, keep:",[133,1890,1891,1894,1897,1899,1901,1904],{},[136,1892,1893],{},"the operator’s problem and intended outcome;",[136,1895,1896],{},"the current scope and hard constraints;",[136,1898,1590],{},[136,1900,1593],{},[136,1902,1903],{},"one representative task the workflow has already completed;",[136,1905,1906],{},"the evidence that showed it completed successfully.",[11,1908,1909],{},"This baseline is the control for the next run. Without it, “improvement” becomes whatever the latest reviewer prefers.",[11,1911,1912],{},"The terminal condition should describe observable state. “The article is good” is not enough. “The draft exists, required sections are present, material claims have supporting evidence or an explicit unresolved status, blocking review findings are repaired, and sanitization checks pass” gives the orchestrator something concrete to evaluate.",[11,1914,1915],{},"It also makes the stopping rule visible. A reviewer can always imagine another improvement. The workflow should not remain open merely because more polish is possible.",[18,1917,1919],{"id":1918},"let-agents-test-the-workflow-as-first-time-operators","Let agents test the workflow as first-time operators",[11,1921,1922],{},"My preferred setup has one refinement agent coordinating several independent workflow runs. The coordinating agent is not there to perform all the work itself. It gives subagents a realistic task, lets them use the workflow, and preserves what happened.",[11,1924,1925],{},"The runners should not be told which failure you expect them to find. That primes them to confirm the diagnosis. Give them the kind of instruction a real user would give, with only the context a normal run would have.",[11,1927,1928],{},"A test instruction can be this small:",[1729,1930,1935],{"className":1931,"code":1933,"language":1934,"meta":64},[1932],"language-text","Use the project workflow to produce the requested article.\nWork as if this is your first time using it.\nUse the context and tools the workflow provides.\nDo not change the workflow while running it.\nStop when its completion conditions are met or when you are genuinely blocked.\n","text",[469,1936,1933],{"__ignoreMap":64},[11,1938,1939],{},"The actual topic or task belongs above that instruction. The important part is what is absent: no hint about the suspected defect, no private debugging history, and no checklist that tells the runner what feedback to return.",[11,1941,1942],{},"For an inexpensive workflow, I usually want more than one run. Two or three subagents are often enough to expose whether a finding repeats. They can receive different representative tasks, or the same task when consistency is the concern. For higher-cost work, one runner plus a targeted replay may be sufficient.",[11,1944,1945],{},"The refinement agent should collect a compact receipt from every run:",[133,1947,1948,1951,1954,1957,1960,1963],{},[136,1949,1950],{},"the user-like instruction the runner received;",[136,1952,1953],{},"the workflow and version it used;",[136,1955,1956],{},"the final outcome and whether the terminal condition passed;",[136,1958,1959],{},"important tool calls, retries, and recovery actions;",[136,1961,1962],{},"any point where state advanced incorrectly;",[136,1964,1965],{},"the runner’s post-run feedback.",[11,1967,1968],{},"This is not the operator watching every tool call. The operator delegates the observation work and receives a synthesized decision packet.",[18,1970,1972],{"id":1971},"interview-the-agents-after-they-finish","Interview the agents after they finish",[11,1974,1975],{},"The run trace shows what the agent did. It does not always show where the agent hesitated, which assumption it made, or what it wished the workflow had supplied. I ask those questions after the run, while the agent still has the experience in context.",[11,1977,1978],{},"Useful questions are concrete:",[1478,1980,1981,1984,1987,1990,1993,1996,1999,2002],{},[136,1982,1983],{},"Where did you hesitate or have to investigate before you could continue?",[136,1985,1986],{},"Which decision did you make that the workflow did not clearly resolve?",[136,1988,1989],{},"What context did you need but not receive at the point of use?",[136,1991,1992],{},"Was any tool difficult to find, understand, or call correctly?",[136,1994,1995],{},"What workaround did you use?",[136,1997,1998],{},"Did the friction threaten the final outcome, or did it only add effort?",[136,2000,2001],{},"What part of the workflow was clearer than expected?",[136,2003,2004],{},"If you changed one generic thing for the next agent, what would it be? What would you leave alone?",[11,2006,2007],{},"The last question matters. Agents can identify useful friction without concluding that every friction needs a fix.",[11,2009,2010],{},"The coordinator can run these as separate debrief sessions. Keeping the runners independent until after their answers are recorded avoids early consensus. One agent may report missing context while another finds the context immediately but struggles with the tool contract. That difference is part of the signal.",[11,2012,2013],{},"If there are several runners, the coordinating agent can spawn a debrief subagent to hold a short feedback session with each one and normalize the answers into the same fields. That subagent collects evidence; it does not decide what the workflow should change. The coordinator keeps the gate.",[11,2015,2016],{},"A feedback record does not need to be long:",[1729,2018,2021],{"className":2019,"code":2020,"language":1734,"meta":64},[1732],"run: workflow-refinement-trial-02\noutcome: passed\nfriction: \"I had to inspect several broad documents before finding the step contract\"\ndecision_made: \"Used the targeted step packet as the source of truth\"\nworkaround: \"Recovered with a scoped lookup\"\nconsequence: latency_only\nsuggested_change: \"Make the targeted packet easier to discover\"\nrunner_confidence: medium\n",[469,2022,2020],{"__ignoreMap":64},[11,2024,2025],{},"The refinement agent can now compare the reported experience with the trace and final state. This is more useful than asking a reviewer to critique the workflow in the abstract.",[11,2027,2028,2029,2034],{},"Anthropic’s ",[304,2030,2033],{"href":2031,"rel":2032},"https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fdemystifying-evals-for-ai-agents",[308],"guide to agent evaluations"," provides useful language for separating a task, trial, trajectory, and outcome. I use that distinction as supporting structure. The practical method is still to let agents perform realistic work and then ask them what the trace does not reveal.",[11,2036,2037],{},"One successful replay shows that the path is possible, not that it is consistent. Use more trials when consistency matters, scaled to the risk and cost of failure.",[18,2039,2041],{"id":2040},"synthesize-the-feedback-without-accepting-all-of-it","Synthesize the feedback without accepting all of it",[11,2043,2044],{},"After the runs and debriefs, the refinement agent has more feedback than should enter delivery. Its job is to compare accounts, connect them to receipts, and classify the findings before suggesting a change.",[749,2046,2047,2060],{},[752,2048,2049],{},[755,2050,2051,2054,2057],{},[758,2052,2053],{},"Finding",[758,2055,2056],{},"Meaning",[758,2058,2059],{},"What to do",[765,2061,2062,2073,2084,2095,2105],{},[755,2063,2064,2067,2070],{},[770,2065,2066],{},"Blocking defect",[770,2068,2069],{},"The workflow cannot meet an accepted criterion, violates a hard constraint, or advances state incorrectly.",[770,2071,2072],{},"Fix before accepting the run.",[755,2074,2075,2078,2081],{},[770,2076,2077],{},"Bounded repair",[770,2079,2080],{},"A specific correction inside the accepted scope would restore the outcome.",[770,2082,2083],{},"Route the smallest repair to the responsible layer.",[755,2085,2086,2089,2092],{},[770,2087,2088],{},"Normal friction",[770,2090,2091],{},"The agent needed reasonable investigation or recovery but still reached the outcome safely.",[770,2093,2094],{},"Record only if useful; do not change the workflow by default.",[755,2096,2097,2099,2102],{},[770,2098,1656],{},[770,2100,2101],{},"A different approach may be nicer, but the accepted outcome still passes.",[770,2103,2104],{},"Keep out of delivery unless the operator changes the plan.",[755,2106,2107,2110,2113],{},[770,2108,2109],{},"Scope change",[770,2111,2112],{},"The suggestion changes the goal, audience, capability, or delivery boundary.",[770,2114,2115],{},"Treat it as a separate decision, not refinement of the current run.",[11,2117,2118],{},"The synthesis can be a simple table:",[749,2120,2121,2140],{},[752,2122,2123],{},[755,2124,2125,2128,2131,2134,2137],{},[758,2126,2127],{},"Observation",[758,2129,2130],{},"Seen in",[758,2132,2133],{},"Outcome effect",[758,2135,2136],{},"Likely layer",[758,2138,2139],{},"Gate decision",[765,2141,2142,2159,2176],{},[755,2143,2144,2147,2150,2153,2156],{},[770,2145,2146],{},"Required context was absent at the point of use",[770,2148,2149],{},"3 of 3 runs",[770,2151,2152],{},"One blocked, two guessed",[770,2154,2155],{},"Context and handoff",[770,2157,2158],{},"Admit as a blocker",[755,2160,2161,2164,2167,2170,2173],{},[770,2162,2163],{},"Runner read more broadly than expected",[770,2165,2166],{},"1 of 3 runs",[770,2168,2169],{},"Added latency; outcome passed",[770,2171,2172],{},"Normal task friction",[770,2174,2175],{},"Record, do not change",[755,2177,2178,2181,2184,2187,2189],{},[770,2179,2180],{},"Reviewer preferred a different article structure",[770,2182,2183],{},"1 review",[770,2185,2186],{},"No accepted criterion failed",[770,2188,1656],{},[770,2190,2191],{},"Keep out of delivery",[11,2193,2194,2195,2199],{},"This is where the orchestrator acts as a gatekeeper. Runners and reviewers should report what they find, but ",[304,2196,2198],{"href":2197},"\u002Flibrary\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback","feedback is not automatically delivery scope",". The orchestrator admits findings only when they protect the outcome that was already agreed.",[11,2201,2202],{},"We saw this distinction during a cold-start replay of one of our own workflows. The agent did some broad reading that added latency. It also found the relevant path, recovered with targeted inspection, and reached the terminal condition. The friction was real, but it did not block the goal or make the result unsafe. Rewriting the workflow around that single inconvenience would have been a weak use of the evidence.",[11,2204,2205],{},"Friction will always exist in work performed by agents. The useful question is whether it exposes a repeatable failure with a meaningful consequence.",[18,2207,2209],{"id":2208},"trace-the-issue-to-the-correct-layer","Trace the issue to the correct layer",[11,2211,2212],{},"A symptom appears where the agent encounters it. The cause may sit somewhere else.",[749,2214,2215,2228],{},[752,2216,2217],{},[755,2218,2219,2222,2225],{},[758,2220,2221],{},"Layer",[758,2223,2224],{},"Typical signal",[758,2226,2227],{},"Appropriate refinement",[765,2229,2230,2241,2252,2262,2273,2284,2295],{},[755,2231,2232,2235,2238],{},[770,2233,2234],{},"Intent and acceptance",[770,2236,2237],{},"Different agents cannot agree on what done means.",[770,2239,2240],{},"Clarify the outcome, constraint, or terminal condition.",[755,2242,2243,2246,2249],{},[770,2244,2245],{},"Workflow contract",[770,2247,2248],{},"Steps overlap, dependencies are unclear, or outputs do not hand off cleanly.",[770,2250,2251],{},"Repair step boundaries, dependencies, or output contracts.",[755,2253,2254,2256,2259],{},[770,2255,2155],{},[770,2257,2258],{},"A specialist must rediscover facts the prior step already knew.",[770,2260,2261],{},"Pass a smaller, explicit context packet with source refs and expectations.",[755,2263,2264,2267,2270],{},[770,2265,2266],{},"Tool surface",[770,2268,2269],{},"The right operation exists but is hard to find or poorly described.",[770,2271,2272],{},"Improve tool selection, names, schemas, or usage guidance.",[755,2274,2275,2278,2281],{},[770,2276,2277],{},"Runtime enforcement",[770,2279,2280],{},"Invalid output advances state, stale contracts remain active, or grants do not match the step.",[770,2282,2283],{},"Fix validation, synchronization, permissions, or state transitions in code.",[755,2285,2286,2289,2292],{},[770,2287,2288],{},"Specialist behavior",[770,2290,2291],{},"The inputs and tools are sufficient, but the agent applies weak judgment or produces poor work.",[770,2293,2294],{},"Refine the role, examples, evaluation criteria, or model choice.",[755,2296,2297,2300,2303],{},[770,2298,2299],{},"Environment",[770,2301,2302],{},"A provider, credential, network, or local service is temporarily unavailable.",[770,2304,2305],{},"Repair the environment or define bounded recovery; do not rewrite the workflow first.",[11,2307,2308],{},"This layer map prevents prompt-shaped fixes for code-shaped problems.",[11,2310,2311],{},"In one content workflow run, a step returned output that did not match its declared result schema. At first glance, that could look like an agent-quality problem. Investigation showed two runtime causes: an updated workflow definition had not refreshed a cached generated contract, and the result schema existed but was not enforced before state mutation.",[11,2313,2314],{},"We fixed the reusable layer. Contract generation became version-aware, and result validation moved in front of the state transition. In the next verification, malformed output was rejected without advancing the workflow; corrected output completed the step. The important improvement was not a new instruction telling one agent to “be more careful.” It was enforcement of an invariant that every agent should be able to rely on.",[18,2316,2318],{"id":2317},"repair-the-generic-cause-one-change-at-a-time","Repair the generic cause, one change at a time",[11,2320,2321],{},"Once the layer is clear, make the smallest change that explains the evidence.",[11,2323,2324],{},"A good refinement should answer four questions:",[1478,2326,2327,2330,2333,2336],{},[136,2328,2329],{},"What observed failure are we correcting?",[136,2331,2332],{},"Which accepted criterion did it threaten?",[136,2334,2335],{},"Why does the cause belong to this layer?",[136,2337,2338],{},"What replay would distinguish a real fix from a one-off success?",[11,2340,2341],{},"Avoid hard-coding the example that exposed the problem. If one research query fails because the workflow cannot carry source context between steps, do not add that query to a prompt. Repair the handoff contract. If one malformed result advances state, do not describe the correct JSON more forcefully. Validate the result mechanically.",[11,2343,2344],{},"Change one layer when possible, then rerun. Simultaneous edits to the prompt, tools, step structure, and runtime may produce a passing result, but they make it difficult to know which change mattered or which one introduced a regression.",[18,2346,2348],{"id":2347},"rerun-with-fresh-agents","Rerun with fresh agents",[11,2350,2351],{},"A refinement is not verified only by the agent that already knows the investigation.",[11,2353,2354],{},"Start fresh subagents with the kind of request the workflow is meant to receive. They should rely on the workflow’s own context, tools, handoffs, and success criteria. They should not receive the private explanation used to diagnose the previous failure.",[11,2356,2357],{},"Check both the result and the path:",[133,2359,2360,2363,2366,2369,2372,2375],{},[136,2361,2362],{},"Did the workflow reach the required environment state?",[136,2364,2365],{},"Did invalid intermediate output fail safely?",[136,2367,2368],{},"Did each specialist receive enough context to act without avoidable investigation?",[136,2370,2371],{},"Did the orchestrator keep preferences and scope changes out of delivery?",[136,2373,2374],{},"Did recovery preserve the accepted outcome?",[136,2376,2377],{},"Did the run stop when the terminal condition became true?",[11,2379,2380],{},"Then repeat the debrief. Ask the same questions so the before-and-after feedback is comparable. If the agents still report the same consequential guess or workaround, the change did not repair the operating experience even if the output happened to pass once.",[11,2382,2383],{},"For repeatable failure modes, turn the observed case into a regression task. Anthropic recommends starting eval sets from the manual checks and real failures teams already use. That keeps evaluation close to actual behavior instead of inventing abstract tests that are easy to pass and hard to trust.",[18,2385,2387],{"id":2386},"ai-agent-workflow-best-practices-for-refinement","AI agent workflow best practices for refinement",[11,2389,2390],{},"The following practices are the ones I would carry into another workflow:",[1478,2392,2393,2399,2405,2411,2417,2423,2429,2435,2441,2447,2453,2463],{},[136,2394,2395,2398],{},[614,2396,2397],{},"Delegate the refinement process to an agent."," The operator defines the goal and decision boundary; the refinement agent coordinates trials, debriefs, synthesis, and verification.",[136,2400,2401,2404],{},[614,2402,2403],{},"Send independent subagents through the workflow."," Give them realistic, minimally primed instructions and let them work from the workflow’s own context.",[136,2406,2407,2410],{},[614,2408,2409],{},"Ask questions after each run."," Collect friction, hidden decisions, missing context, tool confusion, workarounds, and what the runner would leave unchanged.",[136,2412,2413,2416],{},[614,2414,2415],{},"Preserve both receipts and firsthand accounts."," The trace explains what happened; the debrief explains how the operating experience felt to the agent.",[136,2418,2419,2422],{},[614,2420,2421],{},"Compare runs before diagnosing."," Repeated findings are stronger signals than one agent’s preference, but a single safety or state-integrity failure can still be blocking.",[136,2424,2425,2428],{},[614,2426,2427],{},"Freeze the accepted outcome."," Keep the goal, constraints, acceptance criteria, and terminal condition stable during the refinement cycle.",[136,2430,2431,2434],{},[614,2432,2433],{},"Classify every finding."," Distinguish blockers, repairs, normal friction, preferences, and scope changes before admitting work.",[136,2436,2437,2440],{},[614,2438,2439],{},"Diagnose the layer before choosing the fix."," Do not solve runtime failures with longer prompts or specialist failures with more orchestration.",[136,2442,2443,2446],{},[614,2444,2445],{},"Repair reusable causes."," Prefer contracts, validation, clearer context, and better tool interfaces over examples hard-coded for one run.",[136,2448,2449,2452],{},[614,2450,2451],{},"Rerun with fresh agents and the same debrief."," Verification should succeed without hidden knowledge from the debugging session, and the reported friction should materially improve.",[136,2454,2455,2458,2459,2462],{},[614,2456,2457],{},"Set a stopping rule."," Microsoft’s ",[304,2460,1565],{"href":313,"rel":2461},[308]," calls for clear acceptance criteria and an iteration cap so refinement loops do not run indefinitely.",[136,2464,2465,2468],{},[614,2466,2467],{},"Accept normal friction."," Change the workflow when evidence shows a meaningful, repeatable consequence—not simply because another improvement is imaginable.",[18,2470,2472],{"id":2471},"stop-at-reliable-not-frictionless","Stop at reliable, not frictionless",[11,2474,2475],{},"The goal of workflow refinement is not to remove judgment, variability, or every moment of investigation. It is to make the accepted outcome reachable, inspectable, and recoverable under realistic conditions.",[11,2477,2478],{},"That gives the refinement orchestrator a bounded loop:",[1478,2480,2481,2484,2487,2490,2493,2496,2499,2502],{},[136,2482,2483],{},"preserve the baseline;",[136,2485,2486],{},"send subagents through representative tasks;",[136,2488,2489],{},"preserve each trajectory and outcome;",[136,2491,2492],{},"debrief the runners;",[136,2494,2495],{},"compare and classify the findings;",[136,2497,2498],{},"repair the smallest reusable cause;",[136,2500,2501],{},"rerun with fresh agents and repeat the questions;",[136,2503,2504],{},"stop when the terminal condition is reliably true.",[11,2506,2507],{},"If a workflow still reaches the goal safely and a fresh agent can work around minor friction, that may be enough. Polish should improve delivery. It should not become a reason to keep the workflow open forever.",{"title":64,"searchDepth":65,"depth":65,"links":2509},[2510,2511,2512,2513,2514,2515,2516,2517,2518,2519],{"id":1861,"depth":65,"text":1862},{"id":1884,"depth":65,"text":1885},{"id":1918,"depth":65,"text":1919},{"id":1971,"depth":65,"text":1972},{"id":2040,"depth":65,"text":2041},{"id":2208,"depth":65,"text":2209},{"id":2317,"depth":65,"text":2318},{"id":2347,"depth":65,"text":2348},{"id":2386,"depth":65,"text":2387},{"id":2471,"depth":65,"text":2472},"A practical method for using agents, independent workflow runs, and post-run debriefs to refine AI workflows without scope drift.",{},"\u002Farticles\u002Fhow-to-refine-ai-agent-workflow","12 min read",[694,863,1834],[583,192,582],[698,587],"Learn how to test, refine, and polish an AI agent workflow after the first version works",{"title":1847,"description":2520},"articles\u002Fhow-to-refine-ai-agent-workflow",[2531,2532,2533],"AI agent workflows","workflow refinement","agent evaluation","workflow","Plp8uxtXgJuYiCJzd-RHv4jpboGkaeZkS9tJo4JvkQg",{"id":2537,"title":2538,"author":6,"body":2539,"category":70,"description":2971,"extension":72,"featured":76,"heroImage":74,"meta":2972,"navigation":76,"path":2973,"publishedAt":1515,"readingTime":2974,"relatedAgents":2975,"relatedArticles":2977,"relatedWorkflows":2978,"searchIntent":2979,"seo":2980,"stem":2981,"topics":2982,"updatedAt":1515,"visual":2534,"__hash__":2986},"articles\u002Farticles\u002Fwhat-ai-agent-handoff-should-include.md","What should an AI agent handoff include?",{"type":8,"value":2540,"toc":2958},[2541,2544,2547,2551,2554,2557,2580,2583,2586,2592,2596,2599,2677,2680,2684,2687,2696,2699,2704,2707,2711,2714,2717,2734,2737,2740,2744,2747,2760,2763,2766,2769,2773,2776,2779,2782,2785,2789,2792,2795,2815,2818,2821,2825,2828,2831,2834,2837,2843,2847,2850,2856,2859,2863,2866,2916,2919,2923,2926,2929,2952,2955],[11,2542,2543],{},"An AI agent handoff should include the next objective, the accepted state and supporting evidence, only the context that changes the next decision, the agent’s authority and tools, the required output and acceptance criteria, recovery guidance, the next destination, and a stopping rule.",[11,2545,2546],{},"That is the minimum useful packet. A role prompt, a conversation transcript, or a message such as “review the draft” may be part of the handoff, but none of them makes the next step executable by itself.",[18,2548,2550],{"id":2549},"a-handoff-message-is-not-an-execution-packet","A handoff message is not an execution packet",[11,2552,2553],{},"Handoffs are often described as transfers between agents. One agent decides that another specialist should take over, calls a handoff tool, and passes some context.",[11,2555,2556],{},"That description covers the routing event. It does not answer the receiving agent’s operating questions:",[133,2558,2559,2562,2565,2568,2571,2574,2577],{},[136,2560,2561],{},"Which output is authoritative?",[136,2563,2564],{},"What has already been accepted?",[136,2566,2567],{},"Which evidence and policies apply?",[136,2569,2570],{},"What may this agent read or change?",[136,2572,2573],{},"What result must it return?",[136,2575,2576],{},"Who decides what happens after the result?",[136,2578,2579],{},"When should it stop?",[11,2581,2582],{},"A capable agent can investigate these questions. That is not always a failure. Research, diagnosis, and discovery may be the work. The avoidable friction is different: forcing the agent to rediscover workflow state the system already knows.",[11,2584,2585],{},"We encountered this distinction while testing our own workflow setup. Fresh agents could work around incomplete context by reading more files and reconstructing prior decisions. They still reached the goal. But broad role-level investigation added latency, while a targeted step packet let the agent move directly to the relevant action. The useful goal was not zero friction. It was to remove system-created guessing.",[11,2587,2588,2589,2591],{},"This is the narrow focus of a handoff packet. The broader ",[304,2590,1468],{"href":1467}," includes tool design, recovery, authority, and orchestration across the whole run. The packet is the local execution surface one agent receives now.",[18,2593,2595],{"id":2594},"include-eight-operating-fields","Include eight operating fields",[11,2597,2598],{},"The following structure is a practical synthesis from our workflow work, not a standard imposed by one agent framework. The fields can be assembled from durable state, defaults, and prior outputs; they do not need to become eight paragraphs in every prompt.",[749,2600,2601,2611],{},[752,2602,2603],{},[755,2604,2605,2608],{},[758,2606,2607],{},"Field",[758,2609,2610],{},"Question it answers",[765,2612,2613,2621,2629,2637,2645,2653,2661,2669],{},[755,2614,2615,2618],{},[770,2616,2617],{},"Objective and ownership",[770,2619,2620],{},"What must happen now, and who owns the next decision?",[755,2622,2623,2626],{},[770,2624,2625],{},"Accepted state and evidence",[770,2627,2628],{},"What is already true, and which refs prove it?",[755,2630,2631,2634],{},[770,2632,2633],{},"Bounded context and policies",[770,2635,2636],{},"Which prior decisions and rules affect this step?",[755,2638,2639,2642],{},[770,2640,2641],{},"Authority and tools",[770,2643,2644],{},"What may the agent inspect, change, or execute?",[755,2646,2647,2650],{},[770,2648,2649],{},"Output contract",[770,2651,2652],{},"What exact result, fields, or artifact must be returned?",[755,2654,2655,2658],{},[770,2656,2657],{},"Acceptance criteria",[770,2659,2660],{},"How can the agent tell that its responsibility is complete?",[755,2662,2663,2666],{},[770,2664,2665],{},"Recovery path",[770,2667,2668],{},"What should happen when an expected input, tool, or criterion fails?",[755,2670,2671,2674],{},[770,2672,2673],{},"Destination and stopping rule",[770,2675,2676],{},"Where does the result go, and when must the agent return control?",[11,2678,2679],{},"Each field removes a different ambiguity. Combining them into a long prose brief often hides those distinctions, so a structured packet is usually easier to inspect.",[18,2681,2683],{"id":2682},"name-the-objective-and-ownership","Name the objective and ownership",[11,2685,2686],{},"“Act as an editor” is a role. “Review the supplied article for unsupported material claims and return findings to the orchestrator” is an objective.",[11,2688,2689,2690,2695],{},"The packet should also state whether control transfers or returns. This varies across architectures. Microsoft’s ",[304,2691,2694],{"href":2692,"rel":2693},"https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fagent-framework\u002Fworkflows\u002Forchestrations\u002Fhandoff",[308],"handoff orchestration"," transfers task ownership to the receiving agent. In a manager or agent-as-tool pattern, the primary agent retains overall responsibility and receives a bounded specialist result.",[11,2697,2698],{},"The receiver should not need to infer which model applies. A useful packet might say:",[413,2700,2701],{},[11,2702,2703],{},"You own the claim review only. Return findings to the orchestrator. Do not revise the article or expand its scope.",[11,2705,2706],{},"That sentence defines both responsibility and its boundary.",[18,2708,2710],{"id":2709},"pass-accepted-state-not-a-scavenger-hunt","Pass accepted state, not a scavenger hunt",[11,2712,2713],{},"A handoff should identify the current authoritative inputs directly. It should name the accepted brief, current draft, relevant predecessor output, and evidence refs. “Use the latest version in the project” moves state resolution back to the receiving agent.",[11,2715,2716],{},"Accepted state is more than a summary of what happened. It separates settled facts from open questions:",[133,2718,2719,2722,2725,2728,2731],{},[136,2720,2721],{},"the angle was accepted;",[136,2723,2724],{},"the draft at a specific ref is current;",[136,2726,2727],{},"two claims are intentionally marked unresolved;",[136,2729,2730],{},"the publication intent is packet only;",[136,2732,2733],{},"no image generation was selected.",[11,2735,2736],{},"This lets the agent preserve prior decisions instead of accidentally reopening them.",[11,2738,2739],{},"Evidence refs matter for the same reason. A reviewer should receive the claim map or source ledger it must evaluate, not a claim that “research was completed.” A downstream agent can then inspect the receipt when necessary without replaying the entire research phase.",[18,2741,2743],{"id":2742},"select-context-that-changes-the-next-decision","Select context that changes the next decision",[11,2745,2746],{},"Conversation history is useful, but it is not automatically the right handoff payload.",[11,2748,1158,2749,2754,2755,2759],{},[304,2750,2753],{"href":2751,"rel":2752},"https:\u002F\u002Fopenai.github.io\u002Fopenai-agents-python\u002Fhandoffs\u002F",[308],"OpenAI Agents SDK handoff guide"," separates small model-generated handoff metadata from application state and from the receiving agent’s main input. It also provides input filters that change which history items the next agent sees. Microsoft’s ",[304,2756,2758],{"href":313,"rel":2757},[308],"orchestration guidance"," recommends deciding whether the next agent needs full raw context, a compacted version, or only a new instruction set.",[11,2761,2762],{},"The practical rule is to include context when it changes a valid action or judgment. Keep the rest as durable references.",[11,2764,2765],{},"For an editorial review, the current voice guide and disclosure policy change the decision. A long transcript about earlier keyword research may not. For a debugging step, the failing test output and accepted requirement matter; unrelated implementation discussion does not.",[11,2767,2768],{},"Full history can still be correct when nuance across the whole conversation is the task. Bounded context is a selection rule, not a blanket instruction to summarize everything.",[18,2770,2772],{"id":2771},"resolve-tools-and-authority-together","Resolve tools and authority together",[11,2774,2775],{},"A tool name without an authority boundary leaves the agent guessing.",[11,2777,2778],{},"The packet should say which operations are available, what they are for, and which side effects are outside the step. If a reviewer can read files and run checks but cannot edit or publish, that boundary belongs beside the tools.",[11,2780,2781],{},"Resolved tools are better than broad discovery when the workflow already knows the target. “Run the website content sync in this directory” is more executable than “use the repository tools to verify the article.” A tool description should still expose important limits and likely failure modes, but the agent should not have to inspect an entire toolbox to locate the intended operation.",[11,2783,2784],{},"Authority should also end with the active responsibility. A review step does not inherit publication rights merely because publication exists later in the workflow.",[18,2786,2788],{"id":2787},"define-the-output-and-acceptance-contract","Define the output and acceptance contract",[11,2790,2791],{},"The receiving agent needs to know what a valid result looks like.",[11,2793,2794],{},"For a claim review, “provide feedback” is weak. A useful output contract could require:",[133,2796,2797,2800,2803,2806,2809,2812],{},[136,2798,2799],{},"finding;",[136,2801,2802],{},"affected claim or section;",[136,2804,2805],{},"evidence basis;",[136,2807,2808],{},"classification;",[136,2810,2811],{},"repair status;",[136,2813,2814],{},"unresolved question.",[11,2816,2817],{},"Acceptance criteria then define completion: all material claims were checked, unsupported claims were removed or marked unresolved, and findings were returned in the expected shape.",[11,2819,2820],{},"The distinction matters. An output schema can prove that required fields exist. Acceptance criteria evaluate whether the responsibility was actually fulfilled. A packet should carry both when the result feeds another agent.",[18,2822,2824],{"id":2823},"include-targeted-recovery-and-a-stopping-rule","Include targeted recovery and a stopping rule",[11,2826,2827],{},"“Retry if needed” is not recovery guidance.",[11,2829,2830],{},"Targeted recovery names the next safe action for failures the workflow can anticipate. If a predecessor handoff was truncated, the packet can provide the exact read needed to recover it. If a source is unavailable, it can tell the reviewer to return an unresolved finding instead of inventing support. If an external action lacks authority, it can require the agent to stop with a structured blocker.",[11,2832,2833],{},"The stopping rule is equally important. It prevents a specialist from turning one responsibility into a broader improvement project.",[11,2835,2836],{},"A reviewer should stop when its checks are complete and return findings. It should not implement every preference. A writer should stop when the accepted repair is made and the required evidence is attached. It should not redesign the workflow.",[11,2838,1158,2839,2842],{},[304,2840,2841],{"href":2197},"orchestrator then triages feedback"," against the accepted plan.",[18,2844,2846],{"id":2845},"a-worked-handoff-packet","A worked handoff packet",[11,2848,2849],{},"The packet below is deliberately compact. Stable project rules and tool schemas can remain durable references; this payload resolves what the next agent needs for one article review.",[1729,2851,2854],{"className":2852,"code":2853,"language":1734,"meta":64},[1732],"step: editorial-review\n\nobjective:\n  task: Review the current article for unsupported material claims.\n  ownership: Return findings to the orchestrator; do not edit or publish.\n\naccepted_state:\n  draft_ref: website\u002Fcontent\u002Farticles\u002Fexample.md\n  angle_status: accepted\n  publication_intent: packet_only\n  evidence_refs:\n    - evidence-item:research-basis\n    - source-ledger:example\n\ncontext:\n  voice_guide_ref: artifact:current-voice-guide\n  disclosure_policy_ref: resource:public-disclosure\n\nauthority:\n  allowed:\n    - read the draft and named evidence\n    - inspect public primary sources\n  prohibited:\n    - modify the draft\n    - create publication jobs\n    - add work outside claim review\n\noutput:\n  required_fields:\n    - claim\n    - evidence_basis\n    - classification\n    - repair_needed\n  acceptance:\n    - every material claim was checked\n    - unsupported claims are identified\n    - preferences are separated from blockers\n\nrecovery:\n  missing_evidence: Return an unresolved finding with the missing ref.\n  truncated_handoff: Read the named predecessor result once.\n\ndestination: orchestrator\nstop_when: The claim report is complete or a blocking input is unavailable.\n",[469,2855,2853],{"__ignoreMap":64},[11,2857,2858],{},"The exact keys can change. The operating questions should not disappear.",[18,2860,2862],{"id":2861},"watch-for-common-handoff-failures","Watch for common handoff failures",[11,2864,2865],{},"Several packets look informative but still force reconstruction:",[133,2867,2868,2874,2880,2886,2892,2898,2904,2910],{},[136,2869,2870,2873],{},[614,2871,2872],{},"Summary only:"," explains what happened but does not identify authoritative state.",[136,2875,2876,2879],{},[614,2877,2878],{},"Role only:"," describes expertise but not the current objective or boundary.",[136,2881,2882,2885],{},[614,2883,2884],{},"History dump:"," passes everything and makes the receiver search for what matters.",[136,2887,2888,2891],{},[614,2889,2890],{},"Tool catalog:"," exposes operations without resolving which one applies or what authority is active.",[136,2893,2894,2897],{},[614,2895,2896],{},"Output without evidence:"," asks for a result but not the receipts its consumer needs.",[136,2899,2900,2903],{},[614,2901,2902],{},"Criteria without recovery:"," defines success but gives no valid response to missing inputs.",[136,2905,2906,2909],{},[614,2907,2908],{},"No destination:"," leaves the agent unsure whether to act, delegate, or return.",[136,2911,2912,2915],{},[614,2913,2914],{},"No stopping rule:"," lets a bounded task expand into open-ended improvement.",[11,2917,2918],{},"These are packet problems even when the model is capable enough to work around them.",[18,2920,2922],{"id":2921},"use-the-first-valid-action-test","Use the first-valid-action test",[11,2924,2925],{},"Give the packet to a fresh agent with a short instruction such as “continue this step.” Then observe what it must do before taking a valid action.",[11,2927,2928],{},"The packet is probably sufficient when the agent can answer:",[133,2930,2931,2934,2937,2940,2943,2946,2949],{},[136,2932,2933],{},"What am I responsible for?",[136,2935,2936],{},"Which input is authoritative?",[136,2938,2939],{},"Which decisions are already settled?",[136,2941,2942],{},"Which tools and side effects are allowed?",[136,2944,2945],{},"What must I return, and where?",[136,2947,2948],{},"What should I do if the expected path fails?",[136,2950,2951],{},"When must I stop?",[11,2953,2954],{},"Some investigation will remain. That is part of agent work. The warning sign is workflow archaeology: searching for the current draft, guessing which policy applies, discovering tool authority by failure, or reconstructing the terminal condition from conversation history.",[11,2956,2957],{},"A good handoff does not eliminate reasoning. It reserves reasoning for the task instead of spending it on avoidable ambiguity.",{"title":64,"searchDepth":65,"depth":65,"links":2959},[2960,2961,2962,2963,2964,2965,2966,2967,2968,2969,2970],{"id":2549,"depth":65,"text":2550},{"id":2594,"depth":65,"text":2595},{"id":2682,"depth":65,"text":2683},{"id":2709,"depth":65,"text":2710},{"id":2742,"depth":65,"text":2743},{"id":2771,"depth":65,"text":2772},{"id":2787,"depth":65,"text":2788},{"id":2823,"depth":65,"text":2824},{"id":2845,"depth":65,"text":2846},{"id":2861,"depth":65,"text":2862},{"id":2921,"depth":65,"text":2922},"A practical handoff packet for AI agents, covering objective, state, evidence, context, tools, output, recovery, ownership, and stopping rules.",{},"\u002Farticles\u002Fwhat-ai-agent-handoff-should-include","10 min read",[2976,693,694],"stackos-sdlc-delivery",[192,583,582],[698,587],"Learn what an AI agent handoff packet should contain",{"title":2538,"description":2971},"articles\u002Fwhat-ai-agent-handoff-should-include",[2983,2984,2985],"AI agent handoffs","agent context","multi-agent workflows","k6fESodspurlGOFrc6Q9pFLkjFqGX6JbXXWUbVod7QY",{"id":2988,"title":2989,"author":6,"body":2990,"category":70,"description":3238,"extension":72,"featured":76,"heroImage":74,"meta":3239,"navigation":76,"path":3240,"publishedAt":3241,"readingTime":3242,"relatedAgents":3243,"relatedArticles":3244,"relatedWorkflows":3246,"searchIntent":3247,"seo":3248,"stem":3249,"topics":3250,"updatedAt":3241,"visual":875,"__hash__":3253},"articles\u002Farticles\u002Fai-agent-experience.md","Agent experience: the missing layer in AI agent orchestration",{"type":8,"value":2991,"toc":3230},[2992,2995,2998,3002,3005,3008,3016,3020,3023,3026,3029,3037,3040,3044,3047,3050,3112,3115,3118,3121,3124,3127,3131,3134,3137,3140,3143,3146,3150,3153,3156,3159,3162,3166,3169,3172,3175,3178,3181,3185,3188,3191,3214,3217,3224,3227],[11,2993,2994],{},"An orchestration plan can be logically correct and still fail at the moment an agent receives its next step. The workflow says “draft the article,” but the agent must discover the brief, infer the audience, locate the allowed tools, reconstruct prior decisions, decide what completion means, and determine where the result belongs.",[11,2996,2997],{},"That gap lives in the agent’s operating environment at the point of action.",[1238,2999],{"caption":3000,"mode":875,"title":3001},"Orchestration is experienced one claimed step at a time: context, authority, tools, outputs, recovery, and a stopping rule.","The workflow an agent actually receives",[11,3003,3004],{},"Agent experience is the per-step operating layer that makes an orchestration plan executable for a fresh agent. Operationally, it is the burden a system places on that agent to search, guess, rediscover, and recover before it can perform valid work.",[11,3006,3007],{},"This definition keeps the idea concrete. Search burden is time spent locating relevant state or instructions. Guessing burden appears when inputs, authority, or completion criteria are ambiguous. Rediscovery burden comes from reconstructing decisions the system already knows. Recovery burden is the work required to understand and repair a failed attempt.",[11,3009,3010,3011,3015],{},"These burdens are separate from the distinctions among an ",[304,3012,3014],{"href":3013},"\u002Flibrary\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator","AI agent, workflow, and orchestrator",". Those components may all be present while the claimed step remains difficult to execute.",[18,3017,3019],{"id":3018},"an-assignment-is-not-yet-an-executable-step","An assignment is not yet an executable step",[11,3021,3022],{},"“Review the implementation” is an assignment. It identifies an activity but leaves most operating questions unanswered.",[11,3024,3025],{},"Which implementation? Review against which requirements? May the reviewer run tests, inspect external systems, or modify files? What evidence should the review produce? Does “ready” mean no defects, no blocking defects, or acceptance of documented risk? If the review finds a problem, who receives it and in what form?",[11,3027,3028],{},"A capable agent can often fill these gaps. That is precisely the problem: successful execution now depends on inference that the orchestration system could have resolved before dispatch.",[11,3030,3031,3032,3036],{},"An executable step should let an agent move from claim to first valid action without rebuilding the workflow in its own context window. This is especially important in an ",[304,3033,3035],{"href":3034},"\u002Flibrary\u002Farticles\u002Fwhat-is-an-agentic-workflow","agentic workflow",", where later actions depend on runtime findings. Dynamic behavior increases the need for explicit local operating conditions; it does not remove it.",[11,3038,3039],{},"The claimed step is therefore the useful unit for examining agent experience.",[18,3041,3043],{"id":3042},"the-claimed-step-packet","The claimed-step packet",[11,3045,3046],{},"When an agent claims a step, it should receive a bounded packet containing what that step needs now. This prepared execution surface selects from project state instead of passing all of it through.",[11,3048,3049],{},"A useful packet includes:",[133,3051,3052,3058,3064,3070,3076,3082,3088,3094,3100,3106],{},[136,3053,3054,3057],{},[614,3055,3056],{},"Purpose:"," why the work exists and what downstream decision or action it supports.",[136,3059,3060,3063],{},[614,3061,3062],{},"Instructions and policies:"," the relevant rules, already selected for this step.",[136,3065,3066,3069],{},[614,3067,3068],{},"Completion criteria:"," observable conditions that distinguish finished work from plausible-looking progress.",[136,3071,3072,3075],{},[614,3073,3074],{},"Exact tools:"," callable operations, expected use, and important limitations.",[136,3077,3078,3081],{},[614,3079,3080],{},"Resolved inputs:"," concrete artifact references, resource identifiers, prior outputs, and configuration values rather than instructions to “find the latest.”",[136,3083,3084,3087],{},[614,3085,3086],{},"Bounded context:"," enough history to understand the work without replaying the whole run.",[136,3089,3090,3093],{},[614,3091,3092],{},"Output contracts:"," required fields, artifact formats, evidence, and status semantics.",[136,3095,3096,3099],{},[614,3097,3098],{},"Direct handoff:"," where the result goes and what the next actor needs from it.",[136,3101,3102,3105],{},[614,3103,3104],{},"Targeted recovery:"," likely failure modes and the next safe action for each one.",[136,3107,3108,3111],{},[614,3109,3110],{},"A stopping rule:"," when to return control instead of expanding the task.",[11,3113,3114],{},"These fields turn hidden orchestration knowledge into local operating knowledge.",[11,3116,3117],{},"The distinction between resolved inputs and broad context matters. A packet should say which approved brief to use, not provide a folder and ask the agent to identify the authoritative version. It should name the relevant test command, not merely mention that tests exist. It should link a predecessor’s accepted artifact, not force the agent to search conversation history for the last apparently complete draft.",[11,3119,3120],{},"Context is useful when it reduces uncertainty. Beyond that point, it becomes another search surface.",[11,3122,3123],{},"The same principle applies to recovery. “Retry if needed” transfers diagnosis back to the agent. A targeted recovery hint might instead say that a truncated handoff can be retrieved with one exact read, that an unavailable credential requires returning the step with a specific reason, or that a validation failure should go back to the producing step with the failed criterion attached.",[11,3125,3126],{},"A good recovery path narrows the next decision without pretending every failure can be anticipated.",[18,3128,3130],{"id":3129},"authority-should-match-the-active-step","Authority should match the active step",[11,3132,3133],{},"Instructions alone do not define what an agent can do. The executable step also needs an authority boundary.",[11,3135,3136],{},"A practical model grants tools and resources when the step becomes active, scoped to the operations and inputs required for that step. Completion, cancellation, or release of the step ends that authority. The agent does not need ambient access to every workflow capability, and it should not have to discover whether a documented operation is actually permitted.",[11,3138,3139],{},"The relationship should be legible: purpose leads to a permitted action, the action produces required evidence, and the evidence has a defined handoff.",[11,3141,3142],{},"If any link is missing, the agent must guess. If tools are described but unavailable, it enters recovery before substantive work begins. If broad tools are available without a step-level purpose, the system invites drift.",[11,3144,3145],{},"Approval can be part of this boundary when risk or organizational policy calls for it, but approval is not inherently required for every step. The important property is that authority is explicit, scoped, and legible to the acting agent.",[18,3147,3149],{"id":3148},"review-feedback-does-not-own-delivery","Review feedback does not own delivery",[11,3151,3152],{},"Independent review is often represented as a simple gate after production. In operation, the reviewer also needs a claimed-step packet: the artifact under review, the governing criteria, relevant evidence, permitted verification tools, and a structured way to report findings.",[11,3154,3155],{},"An independent reviewer still needs the relevant context. It evaluates the work against declared criteria rather than inheriting the producer’s conclusions as facts.",[11,3157,3158],{},"The orchestrator has a different responsibility: adjudicating what the findings are allowed to change. A supported blocker can stop progression. A specific repair can return to the producing step. A preference can remain advice. An unsupported or out-of-scope finding should not expand the delivery.",[11,3160,3161],{},"This is a feedback gate, but not a ritual approval step. It protects the agreed goal from review-driven drift while preserving independent scrutiny where it matters.",[18,3163,3165],{"id":3164},"a-bounded-observation-from-one-stackos-replay","A bounded observation from one StackOS replay",[11,3167,3168],{},"One recent StackOS cold-start replay provides a small implementation example. It should be read as first-party operating evidence, not as a productivity benchmark or universal proof.",[11,3170,3171],{},"During that replay, a draft specialist reported that it had used no tools and made no guesses while completing its assigned work. That report records the agent’s operating behavior alongside the artifact. We did not run a comparative test to isolate why it needed no additional discovery.",[11,3173,3174],{},"Another step received a truncated dependency handoff. Instead of searching broadly, the agent followed the packet’s targeted recovery hint and retrieved the one complete prior-step result it needed. Near the end of the run, the final stopping rule kept the active agent from starting another workflow, changing the workflow setup, or creating unrelated content after the requested outcome had been reached.",[11,3176,3177],{},"The run still contained ordinary latency and friction. Agents had to process context, produce outputs, and move through orchestration boundaries. One fresh subagent missed its bounded execution window. The observation establishes neither lower overhead nor gains across models or workflows.",[11,3179,3180],{},"Within that boundary, the replay records three useful behaviors: one specialist reported no guessing, targeted recovery constrained the response to a partial handoff, and an explicit stopping rule limited drift.",[18,3182,3184],{"id":3183},"the-vague-cold-start-test","The vague cold-start test",[11,3186,3187],{},"A direct way to inspect agent experience is to remove accumulated familiarity.",[11,3189,3190],{},"Give a fresh agent the kind of vague request a real operator might provide. Do not give it the workflow key, the design rationale, or a warm context window containing earlier exploration. Then observe whether the system helps it discover the right workflow and whether the claimed step answers these questions:",[1478,3192,3193,3196,3199,3202,3205,3208,3211],{},[136,3194,3195],{},"What is the first valid action?",[136,3197,3198],{},"Which exact inputs should be used?",[136,3200,3201],{},"Which tools are permitted and available?",[136,3203,3204],{},"What observable criteria define completion?",[136,3206,3207],{},"What must be produced, and where does it go?",[136,3209,3210],{},"What should happen if the expected path fails?",[136,3212,3213],{},"When must the agent stop and return control?",[11,3215,3216],{},"The test exposes friction when the agent must search broadly for policy, infer which artifact is authoritative, guess whether it has permission, recreate prior decisions, or invent a recovery strategy. Those behaviors may still produce a successful result, but they reveal orchestration work leaking into the execution step.",[11,3218,3219,3220,3223],{},"Teams can apply the same test while following a practical guide to ",[304,3221,3222],{"href":810},"building an AI agent workflow",". For each step, record the agent’s first action, unresolved questions, searches, inferred assumptions, unavailable tools, recovery attempts, and work performed after the completion condition. The result is a friction map grounded in behavior rather than a subjective rating.",[11,3225,3226],{},"Some ambiguity belongs to the work, some discovery is intentional, and some failures require judgment. The design target is narrower: stop making each fresh agent reconstruct decisions that the system has already made.",[11,3228,3229],{},"Orchestration determines what should happen next. Agent experience determines whether the next agent can actually do it.",{"title":64,"searchDepth":65,"depth":65,"links":3231},[3232,3233,3234,3235,3236,3237],{"id":3018,"depth":65,"text":3019},{"id":3042,"depth":65,"text":3043},{"id":3129,"depth":65,"text":3130},{"id":3148,"depth":65,"text":3149},{"id":3164,"depth":65,"text":3165},{"id":3183,"depth":65,"text":3184},"AI agent orchestration is experienced one claimed step at a time. Here is how context, authority, tools, recovery, and stopping rules shape whether an agent can execute.",{},"\u002Farticles\u002Fai-agent-experience","2026-07-11","9 min read",[693,694,863],[3245,193,583],"ai-agent-vs-workflow-vs-orchestrator",[698,587],"Understand how to design the operating experience inside AI agent orchestration",{"title":2989,"description":3238},"articles\u002Fai-agent-experience",[3251,1468,3252],"AI agent orchestration","workflow design","uV1oEIIU0bekOi0eZ7egVtz64SWH2q_6b4myaRa7sf0",{"id":3255,"title":3256,"author":6,"body":3257,"category":70,"description":3539,"extension":72,"featured":76,"heroImage":74,"meta":3540,"navigation":76,"path":3541,"publishedAt":3241,"readingTime":3242,"relatedAgents":3542,"relatedArticles":3544,"relatedWorkflows":3545,"searchIntent":3546,"seo":3547,"stem":3548,"topics":3549,"updatedAt":3241,"visual":2534,"__hash__":3550},"articles\u002Farticles\u002Fhow-to-build-ai-agent-workflow.md","How to build an AI agent workflow: start with the problem",{"type":8,"value":3258,"toc":3529},[3259,3262,3265,3269,3276,3280,3283,3286,3306,3309,3312,3318,3322,3325,3331,3337,3343,3349,3352,3356,3359,3362,3365,3370,3373,3376,3380,3383,3386,3389,3395,3399,3402,3405,3446,3449,3452,3455,3459,3462,3465,3468,3471,3474,3478,3481,3484,3487,3490,3494,3497,3526],[11,3260,3261],{},"Start a useful AI agent workflow with an operational problem: something that should move from an uncertain starting state to a useful, verifiable outcome. Models, prompt libraries, and agent diagrams come later.",[11,3263,3264],{},"That distinction changes the design. A chain of prompts describes what the model should say next. An operational contract describes what the system is allowed to do, what state it must preserve, how progress is evaluated, and when the job is finished.",[3266,3267],"article-workflow-visual",{"title":3268,"workflow":698},"Design backward from a useful outcome",[11,3270,3271,3272,3275],{},"This is also what separates a workflow from adjacent concepts. An ",[304,3273,3274],{"href":3013},"agent, workflow, and orchestrator"," can all involve model reasoning, but they carry different responsibilities. The workflow defines the operating boundary. The orchestrator decides how to advance within it. Agents perform bounded work.",[18,3277,3279],{"id":3278},"why-prompt-chains-become-fragile","Why prompt chains become fragile",[11,3281,3282],{},"Prompt chains often look convincing in a prototype. One prompt gathers information, another drafts, and a third reviews. Each stage passes text to the next.",[11,3284,3285],{},"The fragility appears when the input is incomplete, a tool fails, a reviewer finds a real defect, or the work resumes after interruption. The chain has no reliable answer to questions such as:",[133,3287,3288,3291,3294,3297,3300,3303],{},[136,3289,3290],{},"Which facts were verified, and where did they come from?",[136,3292,3293],{},"Is a review comment a blocker, a repair, or an unsupported preference?",[136,3295,3296],{},"Can a failed step be retried without repeating side effects?",[136,3298,3299],{},"What remains unfinished?",[136,3301,3302],{},"Has the requested outcome already been reached?",[136,3304,3305],{},"Which instructions still apply after several rounds of generated text?",[11,3307,3308],{},"Prompting alone does not create durable state or explicit control flow for these questions. A larger context window can hide that gap without closing it.",[11,3310,3311],{},"A prompt chain also tends to mix reasoning, state, and control flow. The model is expected to remember prior decisions, infer the current phase, choose tools, preserve constraints, and decide whether to stop. Small ambiguities accumulate. Later steps inherit summaries of summaries rather than a stable account of the job.",[11,3313,3314,3315,3317],{},"Representing those responsibilities explicitly makes an ",[304,3316,3035],{"href":3034}," easier to inspect when something changes.",[18,3319,3321],{"id":3320},"define-the-job-before-defining-the-agents","Define the job before defining the agents",[11,3323,3324],{},"Start with four descriptions: the problem, the useful outcome, the operator path, and the agent path.",[11,3326,1158,3327,3330],{},[614,3328,3329],{},"problem"," describes the operational gap. “We need a five-agent research system” is an implementation preference. “An editor cannot tell which claims in a draft are supported by the supplied sources” is a problem.",[11,3332,1158,3333,3336],{},[614,3334,3335],{},"useful outcome"," is the state in which that problem has been resolved. It should be inspectable. For the example above, the outcome might be a publishable draft whose material claims are linked to evidence, with unresolved claims clearly identified.",[11,3338,1158,3339,3342],{},[614,3340,3341],{},"operator path"," describes what a person initiating or supervising the workflow must do. What do they provide? Which choices can only they make? What can they inspect or revise? If the operator must repeatedly reconstruct hidden workflow state from chat history, the contract is incomplete.",[11,3344,1158,3345,3348],{},[614,3346,3347],{},"agent path"," describes how the system turns the initial inputs into the outcome. It names the required stages, dependencies, tools, state transitions, and recovery behavior. It should not assume that the agent will infer the intended route from a vague goal.",[11,3350,3351],{},"The two paths should meet at explicit interaction points, but they do not need a mandatory approval after every step. Some workflows can proceed automatically within a narrow boundary. Others need a decision when evidence conflicts, scope changes, or an external side effect is about to occur. The contract should reflect the actual risk rather than adding ceremonial checkpoints.",[18,3353,3355],{"id":3354},"work-backward-from-a-terminal-condition","Work backward from a terminal condition",[11,3357,3358],{},"A workflow needs a definition of done that can survive imperfect execution.",[11,3360,3361],{},"“Produce a good article” is not a terminal condition. Neither is “continue until the reviewer is satisfied.” Both delegate completion to an unbounded judgment.",[11,3363,3364],{},"A stronger terminal condition combines observable state with acceptance criteria. For example:",[413,3366,3367],{},[11,3368,3369],{},"The draft exists, required sections are present, material claims have supporting evidence or an explicit unresolved status, blocking review findings are repaired, and the output passes the sanitization checks.",[11,3371,3372],{},"This gives the orchestrator something concrete to evaluate. It also prevents the workflow from looping because a reviewer can always imagine another improvement.",[11,3374,3375],{},"Terminal conditions should distinguish failure from incompleteness. Missing credentials, unavailable evidence, and contradictory operator requirements may prevent completion. Those states should produce structured recovery information: what failed, what was preserved, and what action could unblock the run.",[18,3377,3379],{"id":3378},"keep-durable-state-outside-the-conversation","Keep durable state outside the conversation",[11,3381,3382],{},"Conversation context is useful working memory. It is a poor system of record.",[11,3384,3385],{},"Durable workflow state should capture the facts needed to resume or audit the job: inputs, source references, decisions, step status, outputs, findings, retries, and unresolved issues. Generated prose can be part of that state, but it should not be the only place where the workflow records what happened.",[11,3387,3388],{},"While building StackOS, we have treated this separation as an authoring constraint. The workflow contracts we are refining represent run state, step boundaries, grants, findings, and outputs independently from an agent’s conversational context. That is implementation experience, not proof that every workflow needs the same storage model. The useful principle is narrower: state required for correct continuation should not depend on a model reconstructing it from dialogue.",[11,3390,3391,3392,3394],{},"Durable state changes the ",[304,3393,1468],{"href":1467},". An agent entering halfway through a run can inspect the current state instead of performing archaeology on a transcript.",[18,3396,3398],{"id":3397},"make-every-step-an-explicit-packet","Make every step an explicit packet",[11,3400,3401],{},"A step should arrive as a bounded packet of work. A role name followed by the entire project history leaves the agent to reconstruct the real assignment.",[11,3403,3404],{},"A useful step packet contains:",[133,3406,3407,3412,3418,3423,3428,3434,3440],{},[136,3408,3409,3411],{},[614,3410,3056],{}," why the step exists and what downstream decision it supports.",[136,3413,3414,3417],{},[614,3415,3416],{},"Inputs:"," the artifacts, references, and state the step may rely on.",[136,3419,3420,3422],{},[614,3421,3086],{}," the relevant constraints without unrelated run history.",[136,3424,3425,3427],{},[614,3426,3074],{}," the operations available for this step, including their scope.",[136,3429,3430,3433],{},[614,3431,3432],{},"Expected outputs:"," the artifact or state change the step must produce.",[136,3435,3436,3439],{},[614,3437,3438],{},"Criteria:"," the checks that determine whether the output is acceptable.",[136,3441,3442,3445],{},[614,3443,3444],{},"Recovery:"," how to report missing inputs, tool failures, ambiguity, or partial work.",[11,3447,3448],{},"Consider a claim-review step. Its purpose is not to “improve the draft.” It is to identify material claims, compare them with allowed evidence, and emit structured findings. Its tools might permit reading sources and recording findings but not rewriting the article. Its output distinguishes supported claims, unsupported claims, and cases where the available evidence is inconclusive.",[11,3450,3451],{},"That packet gives the reviewer enough freedom to reason without giving it ownership of the whole delivery. It also makes failures local. If evidence is missing, the workflow can repair that dependency rather than restart content production.",[11,3453,3454],{},"Exact tools matter because capability is part of the contract. An instruction such as “do not publish” is weaker than a step that has no publishing operation available. Tool boundaries turn behavioral expectations into operating constraints.",[18,3456,3458],{"id":3457},"give-one-orchestrator-ownership-of-progression","Give one orchestrator ownership of progression",[11,3460,3461],{},"A practical default is one reasoning orchestrator that owns progression: inspecting state, selecting the next eligible step, evaluating outputs, and checking the terminal condition. Add a specialist when the task needs a distinct context, tool boundary, or evaluation discipline—not simply because the brief contains several kinds of work.",[11,3463,3464],{},"In a content-production workflow we have been authoring for StackOS, one orchestrator coordinates bounded evidence, writing, claim, voice, and sanitization specialists. Each specialist has a different job and output contract. None independently decides that the entire article is complete.",[11,3466,3467],{},"The orchestrator also acts as the feedback gatekeeper. Review findings are classified before they affect delivery. A supported blocker can reopen an earlier step. A specific, valid repair can become bounded follow-up work. An unsupported preference or a finding outside the agreed scope does not silently expand the job.",[11,3469,3470],{},"This classification is designed to prevent a familiar multi-agent failure mode: every reviewer becomes a new source of authority. Without classification, one agent’s stylistic suggestion can override the original brief, trigger unnecessary rewrites, and create another review cycle. Feedback should change delivery only when the workflow contract says that kind of finding matters.",[11,3472,3473],{},"This is not a universal claim that every system needs exactly one orchestrator. It is a practical default for workflows where several bounded tasks contribute to one outcome. Additional reasoning authorities should have a clear ownership boundary, not merely a different persona.",[18,3475,3477],{"id":3476},"verify-the-cold-start","Verify the cold start",[11,3479,3480],{},"A workflow that succeeds only when its designer supplies unstated context is not finished.",[11,3482,3483],{},"Cold-start verification gives a fresh agent the kind of vague request an actual operator might provide and observes what happens. Does the agent locate the workflow? Does it inspect state and requirements? Does it ask for a genuinely missing choice? Or does it guess the project, invent inputs, and begin producing output?",[11,3485,3486],{},"While refining our StackOS workflow guidance, we use fresh-agent scenarios to expose these gaps. We are testing whether the operating contract leads an unfamiliar agent toward the intended path, not whether the model can improvise a plausible response.",[11,3488,3489],{},"A good cold start should make the safe next action easier than guessing.",[18,3491,3493],{"id":3492},"a-compact-workflow-design-test","A compact workflow design test",[11,3495,3496],{},"Before adding another prompt or specialist, test the workflow with a short sequence of questions:",[1478,3498,3499,3502,3505,3508,3511,3514,3517,3520,3523],{},[136,3500,3501],{},"What operational problem is being resolved?",[136,3503,3504],{},"What observable state counts as a useful outcome?",[136,3506,3507],{},"What does the operator provide, decide, and receive?",[136,3509,3510],{},"What path may the agent take, and which actions are outside its boundary?",[136,3512,3513],{},"Where does durable state live?",[136,3515,3516],{},"Does each step have explicit inputs, tools, outputs, criteria, and recovery?",[136,3518,3519],{},"Who evaluates findings and decides whether they change the run?",[136,3521,3522],{},"Can a fresh agent find the path without private context?",[136,3524,3525],{},"Can the workflow stop deterministically?",[11,3527,3528],{},"If the answers are vague, a more elaborate agent topology can make the ambiguity harder to see. Start with the problem, define the contract, and let the agents occupy only the boundaries the work actually requires.",{"title":64,"searchDepth":65,"depth":65,"links":3530},[3531,3532,3533,3534,3535,3536,3537,3538],{"id":3278,"depth":65,"text":3279},{"id":3320,"depth":65,"text":3321},{"id":3354,"depth":65,"text":3355},{"id":3378,"depth":65,"text":3379},{"id":3397,"depth":65,"text":3398},{"id":3457,"depth":65,"text":3458},{"id":3476,"depth":65,"text":3477},{"id":3492,"depth":65,"text":3493},"A practical way to design AI agent workflows from the outcome backward, with explicit state, step contracts, feedback boundaries, and cold-start verification.",{},"\u002Farticles\u002Fhow-to-build-ai-agent-workflow",[3543,862,694],"stackos-workflow-workflow-author",[3245,193,192],[698,587],"Learn how to build an AI agent workflow from the problem and outcome backward",{"title":3256,"description":3539},"articles\u002Fhow-to-build-ai-agent-workflow",[2531,1526,1525],"I59u29X8EdoopdGoZws9pKiDaHQtKY8L6q2TQAeeyeU",{"id":3552,"title":3553,"author":6,"body":3554,"category":70,"description":3769,"extension":72,"featured":76,"heroImage":74,"meta":3770,"navigation":76,"path":3771,"publishedAt":3772,"readingTime":1516,"relatedAgents":3773,"relatedArticles":3774,"relatedWorkflows":3776,"searchIntent":3777,"seo":3778,"stem":3779,"topics":3780,"updatedAt":1515,"visual":875,"__hash__":3783},"articles\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator.md","AI agent vs. workflow vs. orchestrator: what is the difference?",{"type":8,"value":3555,"toc":3760},[3556,3559,3562,3566,3614,3618,3621,3624,3635,3638,3641,3645,3648,3651,3654,3657,3661,3664,3667,3670,3674,3677,3694,3697,3701,3704,3707,3710,3713,3717,3720,3723,3727,3730,3747,3750],[11,3557,3558],{},"An AI agent owns a bounded responsibility. A workflow defines the durable execution contract. An orchestrator reasons about the whole job: what should happen next, which agent or tool should act, and which feedback belongs in the accepted plan.",[11,3560,3561],{},"The distinction is less about names than ownership. When ownership blurs, agents reconstruct state, workflows become long prompts, and orchestrators accept every plausible suggestion.",[1238,3563],{"caption":3564,"mode":875,"title":3565},"The workflow holds the contract. Agents handle bounded responsibilities. The orchestrator decides how the complete job should move.","One job, three different owners",[749,3567,3568,3581],{},[752,3569,3570],{},[755,3571,3572,3575,3578],{},[758,3573,3574],{},"Component",[758,3576,3577],{},"What it owns",[758,3579,3580],{},"What it should not own",[765,3582,3583,3593,3604],{},[755,3584,3585,3587,3590],{},[770,3586,1387],{},[770,3588,3589],{},"One bounded judgment, transformation, review, or execution responsibility",[770,3591,3592],{},"Quietly redefining the accepted plan",[755,3594,3595,3598,3601],{},[770,3596,3597],{},"Workflow",[770,3599,3600],{},"State, dependencies, tool boundaries, expected outputs, acceptance criteria, and recovery paths",[770,3602,3603],{},"Deciding every exception at runtime",[755,3605,3606,3608,3611],{},[770,3607,1419],{},[770,3609,3610],{},"Next-step reasoning, context assembly, delegation, feedback triage, and recovery",[770,3612,3613],{},"Performing every specialist task or accepting every reviewer idea",[18,3615,3617],{"id":3616},"what-is-an-ai-agent","What is an AI agent?",[11,3619,3620],{},"An AI agent is a model operating under a role contract for the current work. That contract should name its responsibility, relevant context, tools and authority, required output, acceptance criteria, and recovery path.",[11,3622,3623],{},"The work can call for different kinds of agents:",[133,3625,3626,3629,3632],{},[136,3627,3628],{},"A reasoning agent makes a bounded judgment and explains why.",[136,3630,3631],{},"A mechanical agent performs a defined transformation or handoff without taking over strategy.",[136,3633,3634],{},"A review agent challenges another result and returns findings for adjudication.",[11,3636,3637],{},"These roles can use the same underlying model. The important separation is responsibility, not model count.",[11,3639,3640],{},"A good agent experience matters here. The agent should receive the state that changes its next decision, the intended tool path, and a clear stopping rule. It can still investigate when investigation is part of the task. It should not have to rediscover workflow state the system already knows.",[18,3642,3644],{"id":3643},"what-is-a-workflow","What is a workflow?",[11,3646,3647],{},"A workflow is the repeatable shape and durable state of the work. It defines the inputs, stages, dependencies, allowed tools and actions, expected outputs, acceptance criteria, and known recovery paths.",[11,3649,3650],{},"Start the workflow with the problem AI should help solve and the terminal condition for useful completion. Only then decide which steps or roles are necessary.",[11,3652,3653],{},"The workflow should remove avoidable guessing without scripting every conversation. “Claim review must return supported, unresolved, and cut claims with evidence refs” is a useful contract. Prescribing every sentence the reviewer should write is usually not.",[11,3655,3656],{},"This is why a workflow is more useful than a long prompt. A prompt supplies instructions for one turn. A workflow keeps the accepted state, relationships, authority, results, and receipts available across the job.",[18,3658,3660],{"id":3659},"what-is-an-orchestrator","What is an orchestrator?",[11,3662,3663],{},"An orchestrator is the reasoning role responsible for the complete job. It reads the workflow state, chooses the next valid step, assembles context, delegates bounded work, handles exceptions, and keeps delivery aligned with the accepted plan.",[11,3665,3666],{},"It is also the gatekeeper for feedback. A reviewer finding is a claim, not an instruction. The orchestrator checks it against the goal, evidence, root cause, and user impact. It accepts blockers and useful repairs, records preferences when they matter, and rejects suggestions that would expand or redirect the work.",[11,3668,3669],{},"Human input is not a routine orchestrator stage. It is needed when intent, authority, disclosure, or a consequential choice is materially missing. Otherwise the orchestrator should make the bounded decision and keep the job moving.",[18,3671,3673],{"id":3672},"how-do-they-work-together","How do they work together?",[11,3675,3676],{},"Take an article production job:",[1478,3678,3679,3682,3685,3688,3691],{},[136,3680,3681],{},"The workflow stores the sequence from research through drafting and review. It also defines the output expected from each step and the criteria for completion.",[136,3683,3684],{},"The orchestrator reads the request and current state. It may skip an interview because the operator’s experience is already captured, or ask a bounded question because a material claim has no source.",[136,3686,3687],{},"Specialist agents collect evidence, draft the article, review claims, and check disclosure within their assigned boundaries.",[136,3689,3690],{},"Review findings return to the orchestrator. It decides which findings require repair and which are preferences or scope drift.",[136,3692,3693],{},"The job stops when the accepted output exists, material claims are supported or explicitly unresolved, blocking findings are repaired, and the requested verification passes.",[11,3695,3696],{},"In the StackOS model, the agent makes these decisions. StackOS stores the workflow and run state, scopes tool calls, and records what happened. The product is evidence for the separation, not a substitute for the reasoning role.",[18,3698,3700],{"id":3699},"what-did-we-learn-from-refining-real-workflows","What did we learn from refining real workflows?",[11,3702,3703],{},"Two failures made the distinction concrete for us.",[11,3705,3706],{},"First, fresh agents could complete a workflow with incomplete handoffs, but they spent time locating the current state, relevant tools, and expected result. The fix was not another specialist. The workflow and handoff needed to carry the context the system already knew.",[11,3708,3709],{},"Second, reviewers could always imagine another improvement. When the orchestrator treated every suggestion as delivery work, the plan drifted and the job kept expanding. The fix was a stronger gatekeeper: compare feedback with the accepted plan, implement supported repairs, and leave unrelated improvements out.",[11,3711,3712],{},"Both failures involved capable agents. The missing pieces were workflow state and orchestrator judgment.",[18,3714,3716],{"id":3715},"do-you-need-multiple-models","Do you need multiple models?",[11,3718,3719],{},"No. One model can take several roles at different stages, or a team can choose different models for cost, latency, tool use, or domain strength.",[11,3721,3722],{},"The more important separation is responsibility. A research role should preserve sources. A review role should challenge the draft independently. The orchestrator should adjudicate the result without quietly taking over either role.",[18,3724,3726],{"id":3725},"which-part-should-you-design-first","Which part should you design first?",[11,3728,3729],{},"Use this order:",[1478,3731,3732,3735,3738,3741,3744],{},[136,3733,3734],{},"Define the problem, useful outcome, side-effect boundary, and terminal condition.",[136,3736,3737],{},"Build the workflow around the state, dependencies, authority, evidence, and recovery the job needs.",[136,3739,3740],{},"Define what the orchestrator must reason about: next steps, exceptions, feedback, drift, and closeout.",[136,3742,3743],{},"Add an agent only when a bounded responsibility deserves its own context and output contract.",[136,3745,3746],{},"Give the workflow to a fresh agent, observe the work, and ask where it had to guess, investigate, or make an undocumented decision.",[11,3748,3749],{},"This keeps the system grounded in the work. You are not collecting agents because they sound impressive. You are deciding where state lives, who reasons about the whole job, and who owns each necessary piece.",[11,3751,3752,3753,3756,3757,3759],{},"For the adjacent concepts, see ",[304,3754,3755],{"href":3034},"what makes a workflow agentic"," and the practical guide to ",[304,3758,1468],{"href":1467},".",{"title":64,"searchDepth":65,"depth":65,"links":3761},[3762,3763,3764,3765,3766,3767,3768],{"id":3616,"depth":65,"text":3617},{"id":3643,"depth":65,"text":3644},{"id":3659,"depth":65,"text":3660},{"id":3672,"depth":65,"text":3673},{"id":3699,"depth":65,"text":3700},{"id":3715,"depth":65,"text":3716},{"id":3725,"depth":65,"text":3726},"A workflow stores the execution contract. Agents own bounded responsibilities. The orchestrator reasons about the whole job and gates feedback, exceptions, and drift.",{},"\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator","2026-07-09",[693,694],[193,3775],"use-codex-claude-gemini-with-existing-tools",[698,587],"Compare AI agents, workflows, and orchestrators in plain language",{"title":3553,"description":3769},"articles\u002Fai-agent-vs-workflow-vs-orchestrator",[3781,3782,199],"AI agents","orchestrators","5dbHMEnUQm_EksylaO0-_-Uc38_NGPKp4CHwoHL24hA",{"id":3785,"title":3786,"author":6,"body":3787,"category":3951,"description":3952,"extension":72,"featured":73,"heroImage":74,"meta":3953,"navigation":76,"path":3954,"publishedAt":3772,"readingTime":189,"relatedAgents":3955,"relatedArticles":3956,"relatedWorkflows":3957,"searchIntent":3958,"seo":3959,"stem":3960,"topics":3961,"updatedAt":3965,"visual":3801,"__hash__":3966},"articles\u002Farticles\u002Fhow-ai-agents-use-accounts-safely.md","How can AI agents use business accounts without seeing the login?",{"type":8,"value":3788,"toc":3944},[3789,3792,3795,3798,3803,3807,3810,3824,3827,3831,3834,3837,3841,3844,3847,3864,3867,3870,3874,3877,3885,3900,3903,3907,3910,3933,3936],[11,3790,3791],{},"An AI agent does not need a password or API key to use a business account. It needs three things: a safe reference to the account, authority to request a named action, and the result of that action.",[11,3793,3794],{},"The credential can stay inside a trusted action layer. The agent chooses what to request. The action layer validates the request, uses the credential, and returns a sanitized result.",[11,3796,3797],{},"This is the boundary we use in StackOS. It lets the agent work without turning its prompt, workflow state, or logs into a credential store.",[1238,3799],{"caption":3800,"mode":3801,"title":3802},"StackOS keeps the credential inside its local daemon, checks the requested action, and returns a sanitized result.","security","The agent requests. The action layer executes.",[18,3804,3806],{"id":3805},"what-should-the-model-receive","What should the model receive?",[11,3808,3809],{},"The model needs enough information to choose the right connection and action:",[133,3811,3812,3815,3818,3821],{},[136,3813,3814],{},"A provider and account profile name, or another safe reference",[136,3816,3817],{},"Whether the connection is ready",[136,3819,3820],{},"The capabilities and scopes available to it",[136,3822,3823],{},"The contract for the action it wants to request",[11,3825,3826],{},"It does not need the raw token, password, private key, or OAuth refresh token. In StackOS, an opaque credential reference identifies the connection without functioning as the credential itself.",[18,3828,3830],{"id":3829},"where-does-the-secret-stay","Where does the secret stay?",[11,3832,3833],{},"StackOS runs locally on the user’s Mac. The operator enters credentials through the local admin surface, and the daemon owns their storage. When an action runs, StackOS decrypts the credential inside the provider connector. The plaintext value is not serialized into the agent-facing request or response.",[11,3835,3836],{},"That gives us a practical rule: credentials do not belong in prompts, workflow files, project resources, content artifacts, or repository configuration. All of those can be copied, logged, or shared long after the action finishes.",[18,3838,3840],{"id":3839},"what-prevents-an-agent-from-doing-anything-it-wants","What prevents an agent from doing anything it wants?",[11,3842,3843],{},"The useful question is not whether the account is connected. It is whether this agent, in this step, can request this action through this account.",[11,3845,3846],{},"In StackOS, a call passes through a concrete sequence:",[1478,3848,3849,3852,3855,3858,3861],{},[136,3850,3851],{},"StackOS resolves one provider profile instead of handing the agent a collection of credentials.",[136,3853,3854],{},"The agent names a registered action and supplies a payload that must pass that action’s contract.",[136,3856,3857],{},"Inside a workflow, the current step must have an explicit tool grant and a matching action reference. A research step cannot become a publishing step simply because both use the same connected account.",[136,3859,3860],{},"The daemon resolves the credential and calls the provider. Only the connector sees the plaintext secret.",[136,3862,3863],{},"Writes use idempotency protection, and the result is stored as a redacted action receipt with status, timing, and error context.",[11,3865,3866],{},"For a one-off write outside a workflow, the caller must explicitly confirm the named action and state its intent. That is an execution check, not a rule that a human must approve every agent step.",[11,3868,3869],{},"Human approval can still be added when a genuinely consequential action or missing authority calls for it. It is not the main security boundary. A broad token behind an approval click is still a broad token.",[18,3871,3873],{"id":3872},"is-local-software-enough-by-itself","Is local software enough by itself?",[11,3875,3876],{},"No. Running locally reduces how far secrets travel, but location is only one part of the design. Safe account access also needs narrow permissions, typed actions, grant enforcement, input validation, idempotency, redaction, revocation, and an audit trail.",[11,3878,3879,3880,3759],{},"The general principle is least privilege: give the agent only the resources and authority it needs for the current work. That is the same boundary described by ",[304,3881,3884],{"href":3882,"rel":3883},"https:\u002F\u002Fcsrc.nist.gov\u002Fglossary\u002Fterm\u002Fleast_privilege",[308],"NIST’s definition of least privilege",[11,3886,3887,3888,3893,3894,3899],{},"If the action layer is remote, the same boundary has to survive the network. The current ",[304,3889,3892],{"href":3890,"rel":3891},"https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2026-07-28\u002Fbasic\u002Fauthorization",[308],"MCP authorization specification"," uses resource-bound authorization and scope minimization, while the official ",[304,3895,3898],{"href":3896,"rel":3897},"https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Ftutorials\u002Fsecurity\u002Fsecurity_best_practices",[308],"MCP security guidance"," forbids token passthrough. A server should not accept a broad token intended for something else and simply forward it downstream.",[11,3901,3902],{},"An agent can still make a bad decision. These controls limit what it can reach, leave a receipt, and give the operator a place to revoke access or recover.",[18,3904,3906],{"id":3905},"what-should-teams-ask-before-connecting-an-account","What should teams ask before connecting an account?",[11,3908,3909],{},"Ask these questions:",[1478,3911,3912,3915,3918,3921,3924,3927,3930],{},[136,3913,3914],{},"Where is the credential entered, stored, and decrypted?",[136,3916,3917],{},"Can the model, a tool response, or a log ever receive the raw value?",[136,3919,3920],{},"Which exact account, scopes, and actions does the connection allow?",[136,3922,3923],{},"Which workflow steps can request each action?",[136,3925,3926],{},"What prevents a retry from creating a duplicate external change?",[136,3928,3929],{},"What receipt is recorded, and which fields are redacted?",[136,3931,3932],{},"How is access tested, rotated, and revoked?",[11,3934,3935],{},"If those answers are vague, the connection is too broad.",[11,3937,3938,3939,3943],{},"We built StackOS around this boundary because hiding a password in the interface is not enough. The important line is where the credential becomes usable, who can ask for which action, and what trace remains afterward. The ",[304,3940,3942],{"href":3941},"\u002Flibrary\u002Fworkflows","workflow library"," shows how those account actions fit into visible work rather than appearing as isolated tool calls.",{"title":64,"searchDepth":65,"depth":65,"links":3945},[3946,3947,3948,3949,3950],{"id":3805,"depth":65,"text":3806},{"id":3829,"depth":65,"text":3830},{"id":3839,"depth":65,"text":3840},{"id":3872,"depth":65,"text":3873},{"id":3905,"depth":65,"text":3906},"Security","The model does not need the password. It needs a safe account reference, a bounded action, and a trusted execution layer that keeps credentials outside its context.",{},"\u002Farticles\u002Fhow-ai-agents-use-accounts-safely",[695],[3775,193],[587,698],"Understand how AI agents can use connected accounts without receiving credentials",{"title":3786,"description":3952},"articles\u002Fhow-ai-agents-use-accounts-safely",[3962,3963,3964],"AI agent security","credentials","local software","2026-08-14","wd7dvx8k6wtVausS6RmVOOfxXUKfCQAV2gmzOYtR0zM",{"id":3968,"title":3969,"author":6,"body":3970,"category":4127,"description":4128,"extension":72,"featured":76,"heroImage":74,"meta":4129,"navigation":76,"path":4130,"publishedAt":3772,"readingTime":1055,"relatedAgents":4131,"relatedArticles":4132,"relatedWorkflows":4133,"searchIntent":4135,"seo":4136,"stem":4137,"topics":4138,"updatedAt":1515,"visual":1241,"__hash__":4141},"articles\u002Farticles\u002Fuse-codex-claude-gemini-with-existing-tools.md","How to use Codex, Claude Code, or Gemini CLI with the tools you already have",{"type":8,"value":3971,"toc":4119},[3972,3975,3978,3982,3986,3989,3992,3996,3999,4002,4019,4022,4042,4046,4049,4052,4056,4059,4062,4066,4069,4090,4093,4097,4100,4105,4108],[11,3973,3974],{},"You do not need to rebuild your operating setup around whichever AI client you use today. Keep Codex, Claude Code, or Gemini CLI as the place where you direct the work. Connect that client to StackOS through MCP, then let StackOS connect the work to the business systems it actually touches.",[11,3976,3977],{},"The AI chooses the next step. StackOS stores the plan, scopes the tool call, and records what happened. Credentials stay inside the StackOS daemon; the client receives safe references and the result it needs, not your login secrets.",[1238,3979],{"caption":3980,"mode":1241,"title":3981},"Each supported client can reach the same durable project state and the tools available to complete the work.","Keep the AI client. Keep the apps.",[18,3983,3985],{"id":3984},"why-keep-the-ai-client-separate","Why keep the AI client separate?",[11,3987,3988],{},"AI clients improve quickly, and people have different preferences. One person may work in Codex, another in Claude Code, and another in Gemini CLI. Locking the operating process to one chat interface makes switching expensive and fragments the work.",[11,3990,3991],{},"A shared work layer does not make the clients identical or copy private chat history between them. It gives each compatible client access to the same project record: workflows, run plans, dependencies, evidence, connected tools, and audit history.",[18,3993,3995],{"id":3994},"what-does-the-connection-look-like","What does the connection look like?",[11,3997,3998],{},"MCP is the connection layer. StackOS install and repair register a local MCP bridge with the supported clients found on your Mac. Codex, Claude Code, and Gemini CLI still keep their own MCP settings; those settings point to the same local StackOS runtime.",[11,4000,4001],{},"From there, the path is concrete:",[1478,4003,4004,4007,4010,4013,4016],{},[136,4005,4006],{},"The client starts a StackOS session from the directory where you are working.",[136,4008,4009],{},"StackOS resolves that directory to its bound project instead of guessing from the last project someone used.",[136,4011,4012],{},"The AI inspects the relevant workflow or current run and chooses the next step.",[136,4014,4015],{},"That step receives only the context and tools its contract allows.",[136,4017,4018],{},"StackOS validates the call, performs the specific action, and records the result.",[11,4020,4021],{},"Human approval is not a default stage in this path. A client may still apply its own tool-confirmation settings, but StackOS does not add a blanket human checkpoint. The agent should ask when the request leaves intent, authority, a disclosure boundary, or a consequential choice unresolved.",[11,4023,4024,4025,4030,4031,4036,4037,3759],{},"This works because all three clients support MCP, although their configuration differs. See the official setup references for ",[304,4026,4029],{"href":4027,"rel":4028},"https:\u002F\u002Flearn.chatgpt.com\u002Fdocs\u002Fextend\u002Fmcp#connect-codex-to-an-mcp-server",[308],"Codex",", ",[304,4032,4035],{"href":4033,"rel":4034},"https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fmcp",[308],"Claude Code",", and ",[304,4038,4041],{"href":4039,"rel":4040},"https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli\u002Fblob\u002Fmain\u002Fdocs\u002Ftools\u002Fmcp-server.md",[308],"Gemini CLI",[18,4043,4045],{"id":4044},"does-stackos-replace-automation-tools","Does StackOS replace automation tools?",[11,4047,4048],{},"Your existing app remains the system of record. A content team can keep WordPress, a commerce team can keep Shopify, and an engineering team can keep GitHub.",[11,4050,4051],{},"StackOS keeps the execution context between the request and those tools: which project and workflow apply, which step is running, what that step may do, which dependencies are unresolved, what evidence supports the result, and what action was recorded.",[18,4053,4055],{"id":4054},"what-happens-when-you-change-models","What happens when you change models?",[11,4057,4058],{},"Another client does not inherit the private conversation from the old one. It connects from the same workspace, resolves the same StackOS project, and recovers the durable state: the current plan, completed steps, decisions, evidence, and next actions.",[11,4060,4061],{},"Each client still needs its own MCP registration. StackOS install and repair handle that registration for supported hosts, while the project state and business-tool connections remain in one place.",[18,4063,4065],{"id":4064},"a-simple-example","A simple example",[11,4067,4068],{},"Suppose you ask Codex to investigate customer feedback and prepare a fix.",[1478,4070,4071,4078,4081,4084,4087],{},[136,4072,4073,4074,3759],{},"Codex starts StackOS from the project workspace and opens the relevant ",[304,4075,4077],{"href":4076},"\u002Flibrary\u002Fworkflows\u002Fcommunications-customer-feedback-intake","customer feedback workflow",[136,4079,4080],{},"StackOS creates a run plan and gives the intake step its bounded communication context and tools.",[136,4082,4083],{},"Codex investigates the feedback and records the findings with their evidence.",[136,4085,4086],{},"If delivery is in scope and the handoff criteria are met, Codex hands the result to a tracked delivery workflow with its dependencies intact.",[136,4088,4089],{},"If you later continue in Claude Code, it resolves the same project and can see what finished, what remains, and why.",[11,4091,4092],{},"The same pattern works when the starting client is Claude Code or Gemini CLI. The interface changes; the durable work contract does not.",[18,4094,4096],{"id":4095},"what-do-you-need-to-get-started","What do you need to get started?",[11,4098,4099],{},"Install StackOS on your Mac, then open a supported client from the real project directory. Confirm that the StackOS MCP connection is healthy and make one bounded request, for example:",[413,4101,4102],{},[11,4103,4104],{},"Use StackOS for this workspace. Show me the relevant workflow and the first executable step.",[11,4106,4107],{},"Connect the one outside app that request needs. Do not start by wiring every tool your company owns. One real workflow will expose the missing context, permissions, and handoffs much faster.",[11,4109,4110,4111,4113,4114,4118],{},"Browse the ",[304,4112,3942],{"href":3941}," to choose a starting point, or ",[304,4115,4117],{"href":4116},"\u002F#install","download StackOS for Mac"," and connect the client you already use.",{"title":64,"searchDepth":65,"depth":65,"links":4120},[4121,4122,4123,4124,4125,4126],{"id":3984,"depth":65,"text":3985},{"id":3994,"depth":65,"text":3995},{"id":4044,"depth":65,"text":4045},{"id":4054,"depth":65,"text":4055},{"id":4064,"depth":65,"text":4065},{"id":4095,"depth":65,"text":4096},"Getting started","Keep your preferred AI client and existing business apps. Connect each client to the same durable project so plans, tool access, credentials, and receipts do not disappear with the chat.",{},"\u002Farticles\u002Fuse-codex-claude-gemini-with-existing-tools",[],[193,1215],[4134,587],"communications-customer-feedback-intake","Learn how to connect an existing AI client to existing business tools",{"title":3969,"description":4128},"articles\u002Fuse-codex-claude-gemini-with-existing-tools",[4029,4035,4041,4139,4140],"MCP","AI tools","kZJ6ff8HrH3N333-Z9-ulIFArx9mw_SiXwk4VWkGbi8",{"id":4143,"title":4144,"author":6,"body":4145,"category":4415,"description":4416,"extension":72,"featured":76,"heroImage":74,"meta":4417,"navigation":76,"path":4418,"publishedAt":3772,"readingTime":1516,"relatedAgents":4419,"relatedArticles":4420,"relatedWorkflows":4421,"searchIntent":4423,"seo":4424,"stem":4425,"topics":4426,"updatedAt":1515,"visual":2534,"__hash__":4428},"articles\u002Farticles\u002Fwhat-is-an-agentic-workflow.md","What is an agentic workflow? A practical guide to AI-powered work",{"type":8,"value":4146,"toc":4405},[4147,4150,4153,4156,4159,4163,4166,4169,4183,4186,4190,4193,4231,4234,4238,4241,4261,4264,4267,4271,4274,4277,4280,4283,4287,4349,4352,4356,4359,4376,4379,4383,4386,4389,4393,4396],[11,4148,4149],{},"An agentic workflow is a durable execution structure in which AI interprets a goal, chooses the next valid action, uses scoped context and tools, and records the result until the acceptance criteria are met.",[11,4151,4152],{},"The workflow becomes agentic at its decision points. The AI may decide which evidence matters, whether a planned step is still necessary, how to recover from a failed check, or which reviewer finding belongs in the work. State storage, grant enforcement, payload validation, and audit records can remain mechanical.",[11,4154,4155],{},"That separation is useful because adding a model to a fixed chain does not automatically make the work agentic.",[3266,4157],{"title":4158,"workflow":698},"A complete content workflow, from request to verified result",[18,4160,4162],{"id":4161},"what-makes-a-workflow-agentic","What makes a workflow agentic?",[11,4164,4165],{},"Fixed automation follows a known mapping: when this happens, do that. An agentic workflow is useful when the next valid action depends on meaning, evidence, or a changing situation.",[11,4167,4168],{},"Consider four decisions from a content workflow:",[133,4170,4171,4174,4177,4180],{},[136,4172,4173],{},"Is an operator interview needed, or is the relevant experience already captured?",[136,4175,4176],{},"Does the evidence support the proposed angle?",[136,4178,4179],{},"Is a reviewer finding a blocker, a useful repair, a preference, or scope drift?",[136,4181,4182],{},"Has the article met its terminal condition, or is a material claim still unresolved?",[11,4184,4185],{},"Those decisions need reasoning. The workflow still bounds the reasoning with named state, allowed actions, expected outputs, and a stopping rule. Human input is reserved for materially missing intent, authority, disclosure, or a consequential choice; it is not a checkpoint added to every stage.",[18,4187,4189],{"id":4188},"what-should-the-workflow-contain","What should the workflow contain?",[11,4191,4192],{},"A practical agentic workflow needs six things:",[1478,4194,4195,4201,4207,4213,4219,4225],{},[136,4196,4197,4200],{},[614,4198,4199],{},"Problem and outcome."," Name the failure, friction, or decision AI should help with, the useful result, and the side-effect boundary.",[136,4202,4203,4206],{},[614,4204,4205],{},"State and dependencies."," Record what is pending, active, accepted, blocked, or complete, and which later work depends on it.",[136,4208,4209,4212],{},[614,4210,4211],{},"Context, tools, and authority."," Give each step the information and operations it needs without exposing unrelated history or broader access.",[136,4214,4215,4218],{},[614,4216,4217],{},"Decision ownership."," State what the orchestrator decides and which bounded responsibilities belong to specialist agents.",[136,4220,4221,4224],{},[614,4222,4223],{},"Outputs, evidence, and acceptance."," Define what each step must return, which claims need support, and how the result will be verified.",[136,4226,4227,4230],{},[614,4228,4229],{},"Recovery and a terminal condition."," Provide the next safe action for anticipated failures and a concrete definition of done.",[11,4232,4233],{},"These do not need to become six long prompt sections. Stable rules can stay in the workflow, project state, and tool contracts. The agent should receive the subset that changes its next decision.",[18,4235,4237],{"id":4236},"what-happens-from-request-to-result","What happens from request to result?",[11,4239,4240],{},"Imagine an operator asks a tool-using AI client to turn research and firsthand experience into an article. The conversation is only the starting point.",[1478,4242,4243,4246,4249,4252,4255,4258],{},[136,4244,4245],{},"The AI interprets the request, selects the relevant workflow, and adapts a concrete run plan for the topic, sources, channel, image intent, and publication boundary.",[136,4247,4248],{},"The orchestrator reads the current state and chooses the next eligible step. It supplies the context and tools that step needs.",[136,4250,4251],{},"Research, writing, and review agents handle bounded responsibilities. They return evidence, drafts, or findings rather than taking over the whole job.",[136,4253,4254],{},"StackOS stores the plan, scopes each tool call, validates execution, and records the result. It does not choose the content strategy.",[136,4256,4257],{},"The orchestrator adjudicates review findings against the accepted angle and evidence. Not every suggestion enters delivery.",[136,4259,4260],{},"The run ends when the requested artifact exists, material claims are supported or explicitly unresolved, blocking findings are repaired, and verification passes. Publication runs only when it was requested and authorized.",[11,4262,4263],{},"The durable state matters as much as the steps. If research is incomplete, later work stays blocked. If a tool call fails, the receipt shows what happened. If the session changes, the next agent can recover the accepted state without replaying the whole conversation.",[11,4265,4266],{},"This is the model we are building and using in StackOS: the AI chooses the next step; StackOS persists the contract and execution record.",[18,4268,4270],{"id":4269},"where-does-the-agentic-judgment-belong","Where does the agentic judgment belong?",[11,4272,4273],{},"Our early mistake was to treat “agentic” as a reason to add more agents. Running the workflows exposed a different problem.",[11,4275,4276],{},"Fresh agents could often work around missing context. They read more files, inspected more tools, and reconstructed earlier decisions. They reached the result, but the workflow was spending their reasoning on state the system already knew.",[11,4278,4279],{},"Reviewers created another signal. They could always propose one more improvement. When the orchestrator accepted each suggestion, the job drifted beyond the agreed plan.",[11,4281,4282],{},"The useful refinements were clearer handoffs and stronger gatekeeping. Agents still reason about the work. The workflow carries known state, and the orchestrator decides which findings belong in delivery.",[18,4284,4286],{"id":4285},"how-is-this-different-from-a-chatbot-or-fixed-automation","How is this different from a chatbot or fixed automation?",[749,4288,4289,4305],{},[752,4290,4291],{},[755,4292,4293,4296,4299,4302],{},[758,4294,4295],{},"Mode",[758,4297,4298],{},"Best for",[758,4300,4301],{},"How it adapts",[758,4303,4304],{},"What marks completion",[765,4306,4307,4321,4335],{},[755,4308,4309,4312,4315,4318],{},[770,4310,4311],{},"Conversation",[770,4313,4314],{},"A question, explanation, or one-off draft",[770,4316,4317],{},"The model responds within the current context",[770,4319,4320],{},"A useful response is returned",[755,4322,4323,4326,4329,4332],{},[770,4324,4325],{},"Fixed automation",[770,4327,4328],{},"A stable trigger with a known action",[770,4330,4331],{},"Predetermined rules and branches",[770,4333,4334],{},"The configured action finishes",[755,4336,4337,4340,4343,4346],{},[770,4338,4339],{},"Agentic workflow",[770,4341,4342],{},"Multi-step work where evidence or state changes the next action",[770,4344,4345],{},"An agent reasons within a durable execution contract",[770,4347,4348],{},"Acceptance criteria and verification pass",[11,4350,4351],{},"A conversation can call tools, and fixed automation can have many branches. The difference is whether the job needs adaptive judgment plus durable state across the run.",[18,4353,4355],{"id":4354},"where-can-agentic-workflows-be-used","Where can agentic workflows be used?",[11,4357,4358],{},"Use an agentic workflow when:",[133,4360,4361,4364,4367,4370,4373],{},[136,4362,4363],{},"the outcome spans several dependent stages or sessions;",[136,4365,4366],{},"the next step depends on evidence rather than a fixed rule;",[136,4368,4369],{},"different responsibilities need different context or independent review;",[136,4371,4372],{},"connected tools have side effects that require narrow authority and receipts;",[136,4374,4375],{},"failure needs recovery and continuation rather than a full restart.",[11,4377,4378],{},"In engineering, test evidence may change the next implementation step. In content, source quality may change the angle and reviewer feedback must be gated against the brief. In support, an investigation may end in an answer or a structured delivery handoff. The domain changes; the operating problem is the same.",[18,4380,4382],{"id":4381},"when-should-you-use-one","When should you use one?",[11,4384,4385],{},"Do not build one for every request. A normal conversation is enough for a quick question or one-off draft. Fixed automation is usually better for a deterministic transformation. A single explicit tool action does not need a ten-step workflow around it.",[11,4387,4388],{},"The workflow earns its cost when the work needs both judgment and continuity.",[18,4390,4392],{"id":4391},"the-shortest-useful-definition","The shortest useful definition",[11,4394,4395],{},"An agentic workflow is durable, goal-directed work in which AI chooses the next valid action inside explicit boundaries for state, authority, evidence, verification, recovery, and completion.",[11,4397,4398,4399,4402,4403,3759],{},"For the surrounding roles, see ",[304,4400,4401],{"href":3013},"AI agent vs. workflow vs. orchestrator",". For the execution experience each agent needs, see ",[304,4404,1468],{"href":1467},{"title":64,"searchDepth":65,"depth":65,"links":4406},[4407,4408,4409,4410,4411,4412,4413,4414],{"id":4161,"depth":65,"text":4162},{"id":4188,"depth":65,"text":4189},{"id":4236,"depth":65,"text":4237},{"id":4269,"depth":65,"text":4270},{"id":4285,"depth":65,"text":4286},{"id":4354,"depth":65,"text":4355},{"id":4381,"depth":65,"text":4382},{"id":4391,"depth":65,"text":4392},"Agentic workflows","An agentic workflow lets AI choose the next valid action inside a durable contract for state, tools, evidence, verification, recovery, and completion.",{},"\u002Farticles\u002Fwhat-is-an-agentic-workflow",[1058,693],[3245,3775],[587,698,4422],"marketing-campaign-production","Understand what an agentic workflow is, how it works, and when to use one",{"title":4144,"description":4416},"articles\u002Fwhat-is-an-agentic-workflow",[199,3781,4427],"workflow automation","mbFfmMr5UmamUPIjJxDTFSLWo4Kp0tpi4Evlz5cKBHQ",1788839627897]