[{"data":1,"prerenderedAt":6475},["ShallowReactive",2],{"article-search-intent-content-brief-worked-example":3,"related-articles-search-intent-content-brief-worked-example":364},{"id":4,"title":5,"author":6,"body":7,"category":334,"description":335,"extension":336,"featured":337,"heroImage":338,"meta":339,"navigation":340,"path":341,"publishedAt":342,"readingTime":343,"relatedAgents":344,"relatedArticles":348,"relatedWorkflows":351,"searchIntent":354,"seo":355,"stem":356,"topics":357,"updatedAt":361,"visual":362,"__hash__":363},"articles\u002Farticles\u002Fsearch-intent-content-brief-worked-example.md","How do I turn search results into a content brief a writer can use?","StackOS team",{"type":8,"value":9,"toc":325},"minimark",[10,22,27,35,38,41,47,55,58,62,70,73,79,97,109,115,127,131,134,137,159,162,169,210,213,220,224,227,261,269,272,275,301,304,312,316,319,322],[11,12,13,14,21],"p",{},"Define the reader's decision, then give the writer an answer plan, reliable sources, a worked example and clear exclusions. ",[15,16,20],"a",{"href":17,"rel":18},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Ffundamentals\u002Fcreating-helpful-content",[19],"nofollow","Google's helpful-content guidance"," says crediting sources does not replace original effort, so the brief should spell out what the article adds to the results you reviewed.",[23,24,26],"h2",{"id":25},"what-does-the-reader-need-to-decide-or-do","What does the reader need to decide or do?",[11,28,29,30,34],{},"Describe the choice the reader should be able to make after reading. For this demonstration, the selected question is ",[31,32,33],"strong",{},"“When should I update a page's sitemap lastmod date?”"," The assignment is for an editor or developer who has changed a page and needs to choose the value in its existing sitemap.",[11,36,37],{},"The reader can inspect a page diff and find the sitemap entry. Those assumptions remove a lot of potential material: they do not need a sitemap generator comparison or an introduction to every XML tag. They need to decide whether to update the date, keep a known date or omit a date they cannot support.",[11,39,40],{},"Write that finish into the brief:",[42,43,44],"blockquote",{},[11,45,46],{},"Help a small-site editor choose a page's lastmod value from its change record. Use four supplied cases to explain the choice and show what to check in the generated entry.",[11,48,49,50,54],{},"The ",[15,51,53],{"href":52},"\u002Fexamples\u002Fsearch-intent-content-brief-worked-example\u002Fcompleted-brief.md","completed brief"," carries the reader, answer plan, cases, sources, exclusions and checks. Here is how the research shaped those fields.",[11,56,57],{},"That gives the writer a way to judge what belongs. A paragraph on choosing a CMS would need to help with this decision to earn its place. If the intended reader could not inspect a diff, the assignment would need different prerequisites or a simpler way to establish what changed.",[23,59,61],{"id":60},"what-do-the-current-results-reveal-and-which-claims-need-separate-verification","What do the current results reveal, and which claims need separate verification?",[11,63,64,65,69],{},"Use results to inspect the answers available, then take technical claims to their primary sources. In an October 6, 2026 public search for ",[66,67,68],"code",{},"when should I update a page sitemap lastmod date",", four of five selected pages could be opened. This was a small English-language sample without location or device controls, not a controlled Google ranking capture or evidence of demand.",[11,71,72],{},"Each useful observation changed an instruction:",[11,74,75,78],{},[31,76,77],{},"The official rules were already available."," Google's sitemap documentation and the Sitemaps protocol supplied the rule and field definition. The brief therefore keeps the introduction short and asks the writer to spend the explanation on change records.",[11,80,81,84,85,90,91,96],{},[31,82,83],{},"“Small edit” left an important judgment unresolved."," A ",[15,86,89],{"href":87,"rel":88},"https:\u002F\u002Finstantsitemap.com\u002Fresources\u002Fsitemap-structure-explained",[19],"secondary tag explainer"," treated minor and major edits broadly alike. ",[15,92,95],{"href":93,"rel":94},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Fcrawling-indexing\u002Fsitemaps\u002Fbuild-sitemap",[19],"Google's guidance"," makes the change's significance relevant. The brief adds a tiny price correction and asks the writer to explain why it matters.",[11,98,99,102,103,108],{},[31,100,101],{},"An unknown date needed its own answer."," ",[15,104,107],{"href":105,"rel":106},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fblog\u002F2023\u002F06\u002Fsitemaps-lastmod-ping",[19],"Google's discussion of uncertain dates"," supports omitting a date that cannot be determined reliably. The brief adds a page with no reliable change history.",[11,110,111,114],{},[31,112,113],{},"One relevant result remained unread."," A focused lastmod guide could not be opened. Its snippet could not establish what its examples covered, so the brief makes no claim that competing guides lack these cases.",[11,116,49,117,121,122,126],{},[15,118,120],{"href":119},"\u002Fexamples\u002Fsearch-intent-content-brief-worked-example\u002Fresult-observations.md","result-observation sheet"," retains the capture details and how each observation changed the assignment. The ",[15,123,125],{"href":124},"\u002Fexamples\u002Fsearch-intent-content-brief-worked-example\u002Fsource-ledger.md","primary-source sheet"," identifies what the writer can cite for the technical answer.",[23,128,130],{"id":129},"what-useful-answer-or-worked-example-will-this-article-add","What useful answer or worked example will this article add?",[11,132,133],{},"Give the writer a completed exercise that makes the decision visible. Here, four different change records are more useful than asking for “a comprehensive article about sitemap dates.” Each forces a choice the writer must explain.",[11,135,136],{},"For comparison, this rejected outline was authored for the demonstration:",[138,139,140,144,147,150,153,156],"ol",{},[141,142,143],"li",{},"What is a sitemap?",[141,145,146],{},"Every XML tag explained.",[141,148,149],{},"Why recent dates improve SEO.",[141,151,152],{},"Refresh all dates after each deployment.",[141,154,155],{},"Choose a sitemap generator.",[141,157,158],{},"Submit the sitemap and track rankings.",[11,160,161],{},"It spends most of the assignment on other jobs, and it builds in an unsupported promise about recent dates. The deployment instruction also needs correcting against the field's definition. Simply adding sources to those headings would leave the writer pursuing the wrong article.",[11,163,164,165,168],{},"The revised assignment supplies four cases instead. ",[31,166,167],{},"Every page change, date and price below is fictional."," All four pages are rebuilt on October 6, 2026; a recorded update means the change became part of the public page on that date.",[138,170,171,181,191,201],{},[141,172,173,176,177,180],{},[31,174,175],{},"C1 — Export guide:"," its last substantive version was September 12. On October 3, obsolete instructions are replaced with current steps and a verification example; nothing changes afterward. Use ",[66,178,179],{},"2026-10-03"," and explain why the changed task answer supplies the date despite the later rebuild.",[141,182,183,186,187,190],{},[31,184,185],{},"C2 — Retry guide:"," its last substantive version was September 15. Only the footer copyright year changes on October 6; the body, structured data and links stay identical. Keep ",[66,188,189],{},"2026-09-15",".",[141,192,193,196,197,200],{},[31,194,195],{},"C3 — Homepage:"," it aggregates recent content, but reliable change history is unavailable. Only the October 6 build timestamp is known. Omit ",[66,198,199],{},"lastmod"," and identify the missing history.",[141,202,203,206,207,190],{},[31,204,205],{},"C4 — Pricing:"," its last substantive version was September 1. On October 5, the public monthly price changes from $49 to $59 to match the approved price; no other text changes. Use ",[66,208,209],{},"2026-10-05",[11,211,212],{},"C4 makes the writer explain a judgment the research left open: a small correction changes a material fact used in a buying decision. That is our application of the rule, not an example supplied by Google. “Include an edge case” would not give the writer those inputs or that reasoning.",[11,214,49,215,219],{},[15,216,218],{"href":217},"\u002Fexamples\u002Fsearch-intent-content-brief-worked-example\u002Frejected-outline.md","rejected outline"," preserves why the broader approach was dropped. Keeping that reasoning with the assignment helps an editor recognize scope drift if a later draft starts adding generator recommendations again.",[23,221,223],{"id":222},"which-sources-boundaries-and-links-does-the-writer-need","Which sources, boundaries and links does the writer need?",[11,225,226],{},"Give each important claim a source location and a job in the article. For this assignment, three short primary passages are enough:",[228,229,230,240,251],"ul",{},[141,231,232,102,235,239],{},[31,233,234],{},"Google's sitemap documentation, XML additional notes:",[15,236,238],{"href":93,"rel":237},[19],"dependable dates for significant page changes",". Use it to review the cases' change classifications.",[141,241,242,102,245,250],{},[31,243,244],{},"Sitemaps protocol, page-level lastmod row:",[15,246,249],{"href":247,"rel":248},"https:\u002F\u002Fwww.sitemaps.org\u002Fprotocol.html",[19],"an optional field describing the page's modification, rather than sitemap generation",". Use it for the date choice and date-only notation.",[141,252,253,102,256,260],{},[31,254,255],{},"Google's lastmod discussion, uncertain-date paragraph:",[15,257,259],{"href":105,"rel":258},[19],"omit the field when the date cannot be determined reliably",". Use it for C3.",[11,262,263,264,268],{},"The source sheet names the exact sections and their limits, so the writer can reopen the relevant passage without reconstructing the research. For a disputed sentence, the ",[15,265,267],{"href":266},"\u002Flibrary\u002Farticles\u002Fhow-to-fact-check-ai-generated-content\u002F","claim-checking guide"," explains how to compare wording with its source. The content brief itself should settle the assignment's direction before that sentence-level review begins.",[11,270,271],{},"The brief also makes an explicit internal-link decision: no internal destination is required for the commissioned lastmod article. Its complete exercise and primary citations serve the selected task. The claim-checking link above belongs to this article about writing briefs; it is not an instruction to insert that link into every article the brief produces.",[11,273,274],{},"With the reader, cases and sources established, the answer plan becomes specific:",[138,276,277,283,289,295],{},[141,278,279,282],{},[31,280,281],{},"What changed on the page?"," Start from the diff and use C4.",[141,284,285,288],{},[31,286,287],{},"Which date does the record support?"," Compare C1 and C2.",[141,290,291,294],{},[31,292,293],{},"What if the history is unreliable?"," Use C3 and name what the generator owner would need to investigate.",[141,296,297,300],{},[31,298,299],{},"How do I check the result?"," Compare the four decisions with the generated entries. If adapting them to a real site, rebuild an unchanged page again and check whether its value moves without a supported event.",[11,302,303],{},"Keep sitemap creation, submission, CMS configuration, canonical selection, byline dates and search-performance analysis outside this article. Sitemap-index and news-sitemap rules also belong to other assignments. These exclusions prevent an apparently useful detour from replacing the decision the reader came to make.",[11,305,306,307,311],{},"The deliverable is the draft, its completed case table and any unresolved claims. The ",[15,308,310],{"href":309},"\u002Fexamples\u002Fsearch-intent-content-brief-worked-example\u002FREADME.md","packet notes"," explain how the files fit together.",[23,313,315],{"id":314},"could-a-writer-complete-this-brief-without-inventing-experience","Could a writer complete this brief without inventing experience?",[11,317,318],{},"Yes: the primary sources establish the rules, and the labeled cases supply the inputs for applying them. No personal incident or client result is needed.",[11,320,321],{},"To check sufficiency, ask a reader to choose an output for each case using only the brief. They should be able to cite the relevant rule and explain the choice from the supplied record. A request to guess the homepage's history would expose a missing branch; a claim that the price correction improved sales would exceed the evidence.",[11,323,324],{},"If a choice still depends on something the writer must invent, repair that missing input or instruction before asking for more polished prose.",{"title":326,"searchDepth":327,"depth":327,"links":328},"",2,[329,330,331,332,333],{"id":25,"depth":327,"text":26},{"id":60,"depth":327,"text":61},{"id":129,"depth":327,"text":130},{"id":222,"depth":327,"text":223},{"id":314,"depth":327,"text":315},"SEO","Follow a researched question from search results to a complete writing brief, with a rejected outline, verified sources and four worked cases.","md",false,null,{},true,"\u002Farticles\u002Fsearch-intent-content-brief-worked-example","2026-10-06","7 min read",[345,346,347],"branding-channel-strategist","branding-evidence-curator","branding-narrative-writer",[349,350],"how-to-build-ai-content-workflow-that-does-not-sound-generic","how-to-fact-check-ai-generated-content",[352,353],"seo-keyword-research","branding-content-production","Turn observed search results into an original, executable article brief with sources, examples, exclusions and a concrete reader outcome",{"title":5,"description":335},"articles\u002Fsearch-intent-content-brief-worked-example",[358,359,360],"content briefs","search intent","content research","2026-10-07","none","Y4gk243dAxuZHR71862CU0aKwQkwKY7SZm24wQMHdHo",[365,600,862,1171,1369,1607,1846,2089,2509,2714,2821,2897,3028,3100,3288,3361,3551,3735,3851,4070,4174,4419,4770,4992,5228,5558,5794,6001,6171],{"id":366,"title":367,"author":6,"body":368,"category":581,"description":582,"extension":336,"featured":337,"heroImage":338,"meta":583,"navigation":340,"path":584,"publishedAt":361,"readingTime":585,"relatedAgents":586,"relatedArticles":588,"relatedWorkflows":590,"searchIntent":591,"seo":592,"stem":593,"topics":594,"updatedAt":361,"visual":362,"__hash__":599},"articles\u002Farticles\u002Fcheck-ai-workflow-diagram.md","How do I check whether an AI-generated workflow diagram is correct?",{"type":8,"value":369,"toc":574},[370,379,382,386,389,392,402,405,413,417,420,427,455,458,461,485,493,497,500,503,507,510,513,516,519,525,531,553,557,560,571],[11,371,372,373,378],{},"Check each actor, arrow and branch against the written process, then make sure the same explanation is available in text. ",[15,374,377],{"href":375,"rel":376},"https:\u002F\u002Fwww.w3.org\u002FWAI\u002Ftutorials\u002Fimages\u002Fcomplex\u002F",[19],"W3C's guidance for complex images"," calls for a short identifying description and a longer text equivalent of the image's essential information.",[11,380,381],{},"Pay particular attention to the connections. A box can say “queues approved revision” while an arrow lets work reach it without approval.",[23,383,385],{"id":384},"what-exactly-is-the-diagram-supposed-to-explain","What exactly is the diagram supposed to explain?",[11,387,388],{},"Establish who acts, what permits the next step and where the process ends. Keep that written source beside the drawing; the diagram's own labels cannot establish whether it is correct.",[11,390,391],{},"Here, the task is to explain how an announcement reaches a send queue. The process and deliberately flawed drawing were created for this exercise; they are not a captured AI failure.",[11,393,49,394,398,399,190],{},[15,395,397],{"href":396},"\u002Fexamples\u002Fcheck-ai-workflow-diagram\u002Fsource-process.md","written source"," assigns four roles. An author submits a saved draft and its references. An assistant checks reference presence and prepares a packet for a human editor, who approves or requests changes. A separate worker queues the exact approved revision and returns ",[31,400,401],{},"Queued",[11,403,404],{},"Missing references go back to the author for repair and another check. Requested edits also return through checking and a new packet before another editorial decision. The assistant's presence check does not establish that the sources support the claims.",[11,406,407,408,412],{},"If your source leaves the decision owner undefined, resolve that first. The ",[15,409,411],{"href":410},"\u002Flibrary\u002Farticles\u002Fhow-to-build-ai-agent-workflow\u002F","workflow-design guide"," covers those responsibilities.",[23,414,416],{"id":415},"which-errors-can-hide-in-a-diagram-that-looks-plausible","Which errors can hide in a diagram that looks plausible?",[11,418,419],{},"Look for a connection that permits something the source forbids, as well as reversed arrows, the wrong decision owner and missing branches. A drawing can contain all the expected boxes and still describe the wrong process.",[11,421,422,423,426],{},"These are route fragments from the exercise. The flawed drawing has a path through an approval decision ",[31,424,425],{},"and an extra direct route"," from packet preparation to queuing.",[428,429,434,445],"article-evidence-row",{"decision-label":430,"evidence-label":431,"label":432,"record-heading":433},"Corrected route","Flawed route","Packet to queue","Connection",[435,436,437,442],"template",{"v-slot:evidence":326},[11,438,439],{},[31,440,441],{},"Assistant prepares packet → Worker queues approved revision.",[11,443,444],{},"This extra arrow reaches the worker without passing through approval. Preparing the packet is enough to take this route.",[435,446,447,452],{"v-slot:decision":326},[11,448,449],{},[31,450,451],{},"Packet → human editor → approval of this revision → worker queues that revision → Queued.",[11,453,454],{},"Remove the shortcut. The source permits queuing only after the human editor accepts that exact revision.",[11,456,457],{},"Calling the destination “approved” does not supply the skipped decision. The unsupported claim is in the connection between two otherwise legitimate steps.",[11,459,460],{},"The full drawing has three other faults:",[228,462,463,469,475],{},[141,464,465,468],{},[31,466,467],{},"Direction:"," the arrow points from reference checking back to submission. Reverse it: submission starts the check.",[141,470,471,474],{},[31,472,473],{},"Actor:"," the approval diamond names the assistant. It must name the human editor.",[141,476,477,480,481,484],{},[31,478,479],{},"Missing branch:"," nothing connects a change request to the author's revision step. Restore ",[31,482,483],{},"Changes → author revises",", keeping the existing return from revision to reference checking.",[11,486,487,488,492],{},"Check what borders and branching layouts imply too. This exercise defines no ownership lanes or parallel work; its shared return line simply takes two repair paths to the same check. The ",[15,489,491],{"href":490},"\u002Fexamples\u002Fcheck-ai-workflow-diagram\u002Frelationship-audit.md","complete relationship audit"," records the full graph, including the relationships that stay unchanged.",[23,494,496],{"id":495},"what-does-a-successful-render-actually-tell-me","What does a successful render actually tell me?",[11,498,499],{},"It tells you the drawing definition produced an image. It does not compare that drawing with the written process.",[11,501,502],{},"Both SVGs in this exercise were converted successfully to PNG, including the flawed version with its shortcut intact. Connecting two existing boxes produced a drawable line. The rendering tool had no reason to object to the permission that line invented.",[23,504,506],{"id":505},"can-someone-understand-the-process-without-seeing-the-diagram","Can someone understand the process without seeing the diagram?",[11,508,509],{},"Yes, when the text gives them the actors, decisions, return paths and stopping point. “Announcement workflow” names the subject but leaves the process unexplained.",[11,511,512],{},"Here is the complete corrected route in words:",[11,514,515],{},"The author submits a saved draft and its source references to the assistant. If any factual claim lacks a reference, the assistant identifies the gap and returns the draft to the author. The author supplies the missing references; the assistant checks again. Only when all references are present does it prepare a packet containing that exact revision and its references.",[11,517,518],{},"The human editor reads the packet and decides. If changes are needed, the author revises and submits the new revision to the assistant's reference check. It must pass that check, enter a new packet and reach the human editor for another decision.",[11,520,521,522,524],{},"If the editor approves, the separate worker queues the revision named in that approval. It cannot substitute a newer, unreviewed draft. The worker returns ",[31,523,401],{}," for that revision. Sending, delivery, recipient response and queue failures are outside this process.",[11,526,527,528,530],{},"Keep the distinction between a present reference and a supporting source; the ",[15,529,267],{"href":266}," explains the latter. The assistant's first check has a narrower job.",[11,532,533,534,538,539,543,544,548,549,190],{},"A text description of a flawed diagram must preserve its mistakes, so the reader can inspect the same example. Above, the flawed fragment explicitly retains the shortcut. The full ",[15,535,537],{"href":536},"\u002Fexamples\u002Fcheck-ai-workflow-diagram\u002Fflawed.svg","flawed drawing"," has a matching ",[15,540,542],{"href":541},"\u002Fexamples\u002Fcheck-ai-workflow-diagram\u002Fflawed-text.md","visual transcription","; the ",[15,545,547],{"href":546},"\u002Fexamples\u002Fcheck-ai-workflow-diagram\u002Fcorrected.svg","corrected drawing"," has its own ",[15,550,552],{"href":551},"\u002Fexamples\u002Fcheck-ai-workflow-diagram\u002Fcorrected-text.md","complete explanation",[23,554,556],{"id":555},"can-a-reader-follow-the-corrected-diagram-on-the-article-page","Can a reader follow the corrected diagram on the article page?",[11,558,559],{},"Keep the approval condition attached to the action it permits when the page narrows or the layout changes. The comparison here shows a route fragment; the full drawings are linked separately.",[11,561,562,563,566,567,570],{},"In the corrected row, ",[31,564,565],{},"approval of this revision"," leads to ",[31,568,569],{},"worker queues that revision",", with the reason directly below. Check that both phrases and the explanation remain readable together at desktop and narrow widths. If the page leaves only “worker queues” visible, it has lost the condition this example is meant to explain.",[11,572,573],{},"The return route matters for the same reason: an editor's request for changes sends the new revision through checking and review again. An arrow from revision straight to the worker would grant approval the new draft has never received.",{"title":326,"searchDepth":327,"depth":327,"links":575},[576,577,578,579,580],{"id":384,"depth":327,"text":385},{"id":415,"depth":327,"text":416},{"id":495,"depth":327,"text":496},{"id":505,"depth":327,"text":506},{"id":555,"depth":327,"text":556},"AI operations","Check what each workflow arrow permits. Follow an approval shortcut, its correction and the text needed to explain the complete process.",{},"\u002Farticles\u002Fcheck-ai-workflow-diagram","5 min read",[587,347],"branding-claim-auditor",[589,350],"how-to-build-ai-agent-workflow",[353],"Check a workflow diagram against its source, identify an unauthorized route and preserve approval conditions and repair paths in a readable explanation",{"title":367,"description":582},"articles\u002Fcheck-ai-workflow-diagram",[595,596,597,598],"workflow diagrams","AI-generated content","evidence review","accessible diagrams","1c7YmWvDFvGduSct0n4CRHauketaINMV_l9Y3nIv_fs",{"id":601,"title":602,"author":6,"body":603,"category":843,"description":844,"extension":336,"featured":337,"heroImage":338,"meta":845,"navigation":340,"path":846,"publishedAt":361,"readingTime":585,"relatedAgents":847,"relatedArticles":849,"relatedWorkflows":851,"searchIntent":853,"seo":854,"stem":855,"topics":856,"updatedAt":361,"visual":362,"__hash__":861},"articles\u002Farticles\u002Fkeep-brand-voice-consistent-across-ai-tools.md","How do I keep the same brand voice across different AI writing tools?",{"type":8,"value":604,"toc":836},[605,614,617,621,624,627,659,662,666,677,688,697,705,714,720,731,739,747,751,754,757,779,782,790,794,797,814,822,826,833],[11,606,607,608,613],{},"Keep one approved voice guide with an owner, a revision and examples, and have each writing tool read that source. ",[15,609,612],{"href":610,"rel":611},"https:\u002F\u002Fdocs.gitlab.com\u002Fdevelopment\u002Fdocumentation\u002Fai-instruction-files-documentation\u002F",[19],"GitLab does this for documentation",": its authoring instructions refer to, or are generated from, the authoritative style guide.",[11,615,616],{},"The setup below uses Codex CLI and Claude Code in a project folder. Each gets a short instruction file pointing to the same guide. When the guide changes, check both the reference and the resulting prose.",[23,618,620],{"id":619},"what-belongs-in-a-shared-voice-guide","What belongs in a shared voice guide?",[11,622,623],{},"Give the writer concrete choices: who they are addressing, how to explain an action, which tone fits the surface, and an example showing what you mean. Name the person who owns those choices and the current approved revision.",[11,625,626],{},"Draft Pier, an invented app for reviewing articles, provides a small example:",[228,628,629,635,641,647,653],{},[141,630,631,634],{},[31,632,633],{},"Owner and revision:"," the example editorial lead; revision 1.0, approved for this fictional exercise.",[141,636,637,640],{},[31,638,639],{},"Stable voice:"," address someone with a draft to review. Use ordinary words, name the action and explain what happens next.",[141,642,643,646],{},[31,644,645],{},"Announcement tone:"," allow one brief harbor metaphor, then explain the behavior plainly.",[141,648,649,652],{},[31,650,651],{},"Good example:"," “Give your draft a place to land. Assign a reviewer, then leave a note about the decision you need.” It moves from a brief image to a concrete action.",[141,654,655,658],{},[31,656,657],{},"Weak example:"," “Unlock effortless collaboration with our revolutionary review experience.” It praises the experience without telling the reader what to do.",[11,660,661],{},"The explanation beside each example matters. “Use this style” leaves the writer to decide whether to copy the metaphor, sentence length or subject. Here, the intended choice is explicit: a brief metaphor followed by an action.",[23,663,665],{"id":664},"how-do-i-give-codex-cli-and-claude-code-the-same-guidance","How do I give Codex CLI and Claude Code the same guidance?",[11,667,668,669,672,673,676],{},"Keep ",[66,670,671],{},"voice-guide.md"," and the task's ",[66,674,675],{},"facts.md"," in the project folder, then point both clients to those files. Use the guide for expression and the facts for the behavior being described.",[11,678,679,680,683,684,687],{},"For ",[31,681,682],{},"Codex",", add this to the project's ",[66,685,686],{},"AGENTS.md",":",[689,690,695],"pre",{"className":691,"code":693,"language":694,"meta":326},[692],"language-text","Read voice-guide.md and facts.md.\nFollow the guide when writing.\nUse facts.md for product behavior.\nReport the guide revision\nand source paths you read.\n","text",[66,696,693],{"__ignoreMap":326},[11,698,699,704],{},[15,700,703],{"href":701,"rel":702},"https:\u002F\u002Flearn.chatgpt.com\u002Fdocs\u002Fagent-configuration\u002Fagents-md",[19],"OpenAI documents"," that Codex assembles its instructions when a run starts. This instruction explicitly asks it to read the shared files.",[11,706,679,707,710,711,687],{},[31,708,709],{},"Claude Code",", add this to ",[66,712,713],{},"CLAUDE.md",[689,715,718],{"className":716,"code":717,"language":694,"meta":326},[692],"@voice-guide.md\n@facts.md\n\nFollow the guide when writing.\nUse facts.md for product behavior.\nReport the guide revision\nand source paths you read.\n",[66,719,717],{"__ignoreMap":326},[11,721,722,727,728,730],{},[15,723,726],{"href":724,"rel":725},"https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fmemory#import-additional-files",[19],"Claude Code's imports"," resolve relative to ",[66,729,713],{},". Put the import lines directly in that file, outside a code fence.",[11,732,733,734,738],{},"Start a fresh session in the folder and give each client the same task and facts. For the example, ask each to write an in-app announcement explaining review reminders and the action the writer can take. The ",[15,735,737],{"href":736},"\u002Fexamples\u002Fkeep-brand-voice-consistent-across-ai-tools\u002Fvoice-package\u002FREADME.md","example package"," contains the full guides, adapters, facts and reusable prompt.",[11,740,741,742,746],{},"These files handle writing guidance. The ",[15,743,745],{"href":744},"\u002Flibrary\u002Farticles\u002Fuse-codex-claude-gemini-with-existing-tools\u002F","tool-connections guide"," covers sharing connected accounts and saved work between clients.",[23,748,750],{"id":749},"how-do-i-tell-whether-the-drafts-follow-the-guide","How do I tell whether the drafts follow the guide?",[11,752,753],{},"Compare a sentence with the specific choice it should follow. Check the source path and revision actually read as well; the tool's statement that it “followed the guide” does not show whether the wording fits.",[11,755,756],{},"In the recorded Codex exercise, the editorial lead's fictional revision changed announcement openings from a brief metaphor to a literal action naming the reminder or reviewer. These excerpts show the difference:",[428,758,763,771],{"decision-label":759,"evidence-label":760,"label":761,"record-heading":762},"Guide 2.0","Guide 1.0","Opening sentence","Example",[435,764,765,768],{"v-slot:evidence":326},[11,766,767],{},"“Your article is waiting in harbor.”",[11,769,770],{},"Codex used the brief metaphor requested by the original guide. The next sentence named the review-reminder action.",[435,772,773,776],{"v-slot:decision":326},[11,774,775],{},"“Enable review reminders for your article while it waits for your colleague’s review.”",[11,777,778],{},"The later Codex opening starts with the action and names the reminder, as revision 2.0 requests.",[11,780,781],{},"The first opening fit the earlier choice. For a new announcement under revision 2.0, a useful repair is specific: replace the harbor sentence with the action the writer can take. Another literal sentence can also fit; consistency does not require every tool to return identical wording.",[11,783,784,785,789],{},"If the sentence follows the current choice but still leaves the reader confused, ",[15,786,788],{"href":787},"\u002Flibrary\u002Farticles\u002Fhow-to-build-ai-content-workflow-that-does-not-sound-generic\u002F","diagnose what the passage fails to explain",". Repeating “use our voice” will not supply a missing explanation.",[23,791,793],{"id":792},"what-changes-when-i-revise-the-voice-guide","What changes when I revise the voice guide?",[11,795,796],{},"Update the owned guide, fix references that still select an old copy, and check the affected writing in a fresh session.",[138,798,799,802,811],{},[141,800,801],{},"Save the new editorial choice with its owner and revision. In Draft Pier's revision 2.0, announcement openings become literal; the product facts stay the same.",[141,803,804,805,807,808,810],{},"Check ",[66,806,686],{},", ",[66,809,713],{}," and any saved task instructions for references to superseded copies.",[141,812,813],{},"Start a fresh session, inspect which guide it reads, and compare the affected sentence with the new choice.",[11,815,816,817,821],{},"Readable prose can hide a stale reference. In our Codex exercise, an adapter still pointed to guide 1.0, but Codex found guide 2.0, reported the conflict and followed it. Fixing the pointer did not rescue a bad paragraph; it directed the next run to the intended source without that workaround. The ",[15,818,820],{"href":819},"\u002Fexamples\u002Fkeep-brand-voice-consistent-across-ai-tools\u002Fobservations.md","recorded comparison"," keeps the outputs and source reads together.",[23,823,825],{"id":824},"what-should-stay-outside-the-voice-guide","What should stay outside the voice guide?",[11,827,828,829,832],{},"Keep product capabilities, schedules and limits with their factual owner. An approved expression example mentioning a note does not establish a comments feature; ",[15,830,831],{"href":266},"check the product source"," before turning that phrase into an instruction.",[11,834,835],{},"Apply tone to the surface it was chosen for, too. Draft Pier's playful announcement opening is no instruction to make a payment error playful. The same direct voice can tell someone what failed and how to fix it without borrowing the announcement's metaphor.",{"title":326,"searchDepth":327,"depth":327,"links":837},[838,839,840,841,842],{"id":619,"depth":327,"text":620},{"id":664,"depth":327,"text":665},{"id":749,"depth":327,"text":750},{"id":792,"depth":327,"text":793},{"id":824,"depth":327,"text":825},"AI content","Give Codex CLI and Claude Code one shared voice guide, inspect the sources behind their drafts, and reconcile old references when your guidance changes.",{},"\u002Farticles\u002Fkeep-brand-voice-consistent-across-ai-tools",[347,848],"branding-voice-reviewer",[349,850,350],"use-codex-claude-gemini-with-existing-tools",[852,353],"branding-brand-foundation-setup","Keep one approved brand voice guide across AI writing tools, verify which revision each uses, and repair stale references after an editorial change",{"title":602,"description":844},"articles\u002Fkeep-brand-voice-consistent-across-ai-tools",[857,858,859,709,860],"brand voice","AI writing","Codex CLI","editorial guidance","At_6qlz-QBtfWzW3kyb0oQ2fgtLf6W2b7PynMoF-cZ4",{"id":863,"title":864,"author":6,"body":865,"category":843,"description":1155,"extension":336,"featured":337,"heroImage":338,"meta":1156,"navigation":340,"path":1157,"publishedAt":361,"readingTime":585,"relatedAgents":1158,"relatedArticles":1159,"relatedWorkflows":1160,"searchIntent":1162,"seo":1163,"stem":1164,"topics":1165,"updatedAt":361,"visual":362,"__hash__":1170},"articles\u002Farticles\u002Fmake-dense-ai-guide-easier-to-use.md","How do I make a dense AI-written guide easier to use?",{"type":8,"value":866,"toc":1148},[867,876,879,883,890,898,905,909,912,915,920,927,983,986,989,993,1002,1005,1010,1013,1019,1059,1062,1065,1069,1072,1075,1080,1083,1098,1101,1105,1108,1130,1145],[11,868,869,870,875],{},"Choose the form that fits the reader's task: a comparison table, a sequence of steps or a worked example. ",[15,871,874],{"href":872,"rel":873},"https:\u002F\u002Fdevelopers.google.com\u002Fstyle\u002Ftables",[19],"Google's documentation style guide"," recommends tables for items with three or more related pieces of information, with lists or description lists for simpler structures.",[11,877,878],{},"Before shortening a dense passage, find the relationship the reader needs. Cutting the condition that changes their next action would make the page shorter and the instructions wrong.",[23,880,882],{"id":881},"what-is-the-reader-trying-to-do-with-this-passage","What is the reader trying to do with this passage?",[11,884,885,886,889],{},"Decide whether they need to ",[31,887,888],{},"compare options, carry out a task or understand a decision",". Align matching attributes for comparison, put actions in order for a procedure, and explain the reason when a choice needs judgment. Some of that explanation belongs in ordinary prose.",[11,891,892,893,897],{},"The examples below use Cedar Drafts, an invented documentation app. Its rules and review request were written for this exercise. We will restructure selected parts; the ",[15,894,896],{"href":895},"\u002Fexamples\u002Fmake-dense-ai-guide-easier-to-use\u002Fsource-passages.md","complete source passages"," remain available.",[11,899,900,901,904],{},"This assumes the source is sound. If the problem is missing evidence or an unclear point, ",[15,902,903],{"href":787},"diagnose the passage first",". A table cannot supply a fact the writer never had.",[23,906,908],{"id":907},"when-does-a-table-make-the-comparison-clearer","When does a table make the comparison clearer?",[11,910,911],{},"Use a table when the same meaningful attributes apply to several options. Give each attribute a row so the reader can compare one thing at a time.",[11,913,914],{},"Here is an extract from the review-mode paragraph:",[42,916,917],{},[11,918,919],{},"… permits named guest review only when the body has been cleared for that particular outside reviewer, and permits public preview only when the body has been cleared for public release.",[11,921,922,923,926],{},"That condition appears among other details about access and reviewing. Pulling the ",[31,924,925],{},"selected outside-review attributes"," into a table gives them a consistent place:",[928,929,930,946],"table",{},[931,932,933],"thead",{},[934,935,936,940,943],"tr",{},[937,938,939],"th",{},"What to compare",[937,941,942],{},"Named guest review",[937,944,945],{},"Public preview",[947,948,949,961,972],"tbody",{},[934,950,951,955,958],{},[952,953,954],"td",{},"Who can open it",[952,956,957],{},"One invited email address; sign in with that address",[952,959,960],{},"Anyone holding the link; no sign-in",[934,962,963,966,969],{},[952,964,965],{},"Review actions",[952,967,968],{},"Read and comment",[952,970,971],{},"Read only; no comments",[934,973,974,977,980],{},[952,975,976],{},"Required clearance",[952,978,979],{},"Body cleared for this particular outside reviewer",[952,981,982],{},"Body cleared for public release",[11,984,985],{},"“Approved sharing” would be a shorter clearance label, but it would erase the distinction between those two permissions. Sending a public link to one person does not restrict who can open it.",[11,987,988],{},"This table covers these attributes, not every condition for choosing a mode. If the passage only listed the two mode names, a list would do; there would be no shared attributes to align.",[23,990,992],{"id":991},"how-do-i-turn-a-paragraph-into-steps-a-reader-can-follow","How do I turn a paragraph into steps a reader can follow?",[11,994,995,996,1001],{},"Put prerequisites before the actions, show what each action returns and keep a correction beside the check that triggers it. Google's ",[15,997,1000],{"href":998,"rel":999},"https:\u002F\u002Fdevelopers.google.com\u002Fstyle\u002Fprocedures",[19],"procedure guidance"," supports that order and allows small related actions to be combined.",[11,1003,1004],{},"The source's correction is buried in the middle of a paragraph. This extract contains the branch:",[42,1006,1007],{},[11,1008,1009],{},"If either differs, the editor closes the preview, corrects the selected revision or address, and previews again; editing text inside the preview is not possible and does not substitute for selecting the right saved revision.",[11,1011,1012],{},"Here is the complete invitation procedure, arranged so the editor encounters that branch before creating anything.",[11,1014,1015,1018],{},[31,1016,1017],{},"Before starting:"," have the Author role, the saved revision named in the review request, the assigned guest's email and clearance to share that revision's body with that guest. If the role or clearance is missing, leave the draft private and ask the document owner to resolve it.",[138,1020,1021,1032,1039,1050,1056],{},[141,1022,1023,1024,1027,1028,1031],{},"In ",[31,1025,1026],{},"Revisions",", open the requested saved revision. Choose ",[31,1029,1030],{},"Guest review"," and enter the assigned guest's email.",[141,1033,1034,1035,1038],{},"Select ",[31,1036,1037],{},"Preview",". It shows the snapshot body, revision number and invited email.",[141,1040,1041,1042],{},"Compare the revision and recipient with the request.\n",[228,1043,1044,1047],{},[141,1045,1046],{},"If either differs, close the preview, correct the selected revision or address, then preview again. The preview body cannot be edited.",[141,1048,1049],{},"Continue only when both match.",[141,1051,1034,1052,1055],{},[31,1053,1054],{},"Create invitation",". It returns a review link and an expiry time seven calendar days after creation.",[141,1057,1058],{},"Copy the link and expiry into the review request, alongside the matching revision and recipient.",[11,1060,1061],{},"The invitation is prepared when those four fields are in the request. Creating it sends no email; the document owner sends it through the team's existing review channel.",[11,1063,1064],{},"Step 3 determines whether the editor can continue. Moving its correction below the whole procedure would leave creation on the apparent path even after a mismatch.",[23,1066,1068],{"id":1067},"when-is-a-worked-example-better-than-another-rule","When is a worked example better than another rule?",[11,1070,1071],{},"Use an example when the reader needs to understand why an attractive option fails. Supply the requirement, show the relevant behavior and explain the consequence.",[11,1073,1074],{},"The source gives this rule:",[42,1076,1077],{},[11,1078,1079],{},"An editor must not silently turn a requirement into a preference to select the closest match.",[11,1081,1082],{},"The following is a condensed case from the same source, focused on one option's update behavior:",[428,1084,1088,1093],{"decision-label":1085,"evidence-label":1086,"label":942,"record-heading":1087},"Decision","Request and candidate","Option",[435,1089,1090],{"v-slot:evidence":326},[11,1091,1092],{},"The outside reviewer needs to comment and see the author's latest saved edits through the same link. Replacement invitations are excluded. Named guest review allows comments, which makes it worth considering.",[435,1094,1095],{"v-slot:decision":326},[11,1096,1097],{},"Reject named guest review for this request. It shows a frozen snapshot; later edits require a new snapshot and invitation. That conflicts with the required unchanged link. Return the conflict to the document owner before creating a guest link.",[11,1099,1100],{},"“Allows comments” is true but insufficient to justify this choice. The explanation makes the failed requirement visible instead of leaving the reader with an unexplained yes or no.",[23,1102,1104],{"id":1103},"does-the-new-structure-work-inside-the-actual-article","Does the new structure work inside the actual article?",[11,1106,1107],{},"Check the forms where readers will use them, at desktop and narrow widths. A correct source file can still become a table with unclear headers or a correction detached from its step.",[228,1109,1110,1116,1124],{},[141,1111,1112,1115],{},[31,1113,1114],{},"Comparison:"," each value must remain identifiable under its header. If the table scrolls sideways, check that the last column is reachable while the surrounding prose still fits.",[141,1117,1118,1121,1122,190],{},[31,1119,1120],{},"Procedure:"," keep the mismatch branch inside the comparison step, before ",[31,1123,1054],{},[141,1125,1126,1129],{},[31,1127,1128],{},"Decision:"," keep the live-update requirement beside the explanation of the frozen snapshot.",[11,1131,1132,1133,1138,1139,1144],{},"W3C's ",[15,1134,1137],{"href":1135,"rel":1136},"https:\u002F\u002Fwww.w3.org\u002FWAI\u002Ftutorials\u002Ftables\u002F",[19],"table guidance"," explains why headers need structural markup. Its ",[15,1140,1143],{"href":1141,"rel":1142},"https:\u002F\u002Fwww.w3.org\u002FWAI\u002FWCAG22\u002FUnderstanding\u002Freflow.html",[19],"reflow guidance"," allows necessary table relationships to use scrolling while ordinary text still reflows.",[11,1146,1147],{},"Read the procedure once with the wrong recipient in the preview. The page should show you how to correct it before offering the action that creates the invitation.",{"title":326,"searchDepth":327,"depth":327,"links":1149},[1150,1151,1152,1153,1154],{"id":881,"depth":327,"text":882},{"id":907,"depth":327,"text":908},{"id":991,"depth":327,"text":992},{"id":1067,"depth":327,"text":1068},{"id":1103,"depth":327,"text":1104},"Use a comparison table, usable steps and an explained decision to make a dense guide easier to follow, while preserving the conditions that change the answer.",{},"\u002Farticles\u002Fmake-dense-ai-guide-easier-to-use",[347,848,587],[349,350],[353,1161],"seo-content-refresh","Restructure a dense but correct guide so readers can compare options, follow a procedure and understand a decision without losing source conditions",{"title":864,"description":1155},"articles\u002Fmake-dense-ai-guide-easier-to-use",[1166,858,1167,1168,1169],"content design","comparison tables","procedures","editorial review","vTJdHyzuVJ36XwPeEU_7XYVH86JFXCIR0J_6M42foPE",{"id":1172,"title":1173,"author":6,"body":1174,"category":843,"description":1354,"extension":336,"featured":337,"heroImage":338,"meta":1355,"navigation":340,"path":1356,"publishedAt":361,"readingTime":585,"relatedAgents":1357,"relatedArticles":1358,"relatedWorkflows":1360,"searchIntent":1361,"seo":1362,"stem":1363,"topics":1364,"updatedAt":361,"visual":362,"__hash__":1368},"articles\u002Farticles\u002Fmove-ai-draft-into-cms.md","How do I move an AI draft into a CMS without breaking its formatting?",{"type":8,"value":1175,"toc":1347},[1176,1185,1188,1192,1195,1198,1206,1210,1213,1224,1232,1235,1239,1242,1257,1260,1268,1285,1288,1292,1295,1331,1334,1338,1341,1344],[11,1177,1178,1179,1184],{},"Save the approved source, import it as a draft, and compare the converted content and its preview before publishing. ",[15,1180,1183],{"href":1181,"rel":1182},"https:\u002F\u002Fdocs.ghost.org\u002Fadmin-api\u002Fposts\u002Fcreating-a-post",[19],"Ghost's API documentation"," explicitly describes its HTML-to-Lexical conversion as lossy: the HTML it renders can differ from what you supplied.",[11,1186,1187],{},"The awkward failures can be easy to miss. In a small local test, a heading looked fine after conversion, but the link pointing to it stopped working. Here is how to find that kind of change without turning every import into a manual rewrite.",[23,1189,1191],{"id":1190},"what-should-i-save-before-importing-the-draft","What should I save before importing the draft?",[11,1193,1194],{},"Keep an unchanged copy of the approved article, its images and the destinations its links should reach. That gives you something reliable to compare with the CMS draft after conversion.",[11,1196,1197],{},"For a Markdown source, save the actual file, including code indentation and relative links. For a document editor, retain the approved revision and the export you will import. A screenshot helps with appearance, but it cannot tell you whether copied code still contains the same characters.",[11,1199,1200,1201,1205],{},"Make a short list of the structures the article depends on. A nested step, a table header or a figure caption may carry part of the instruction. If the source itself needs a better structure, ",[15,1202,1204],{"href":1203},"\u002Flibrary\u002Farticles\u002Fmake-dense-ai-guide-easier-to-use\u002F","resolve that before the import","; otherwise you will be trying to review editorial changes and conversion changes at once.",[23,1207,1209],{"id":1208},"how-does-the-cms-represent-each-part-of-the-article","How does the CMS represent each part of the article?",[11,1211,1212],{},"Find out which parts become editable blocks and which are stored as embedded HTML. Two drafts can look similar while behaving differently when someone edits them later.",[11,1214,1215,1216,1219,1220,1223],{},"For this article, we ran a synthetic HTML sample through Ghost's official conversion and rendering libraries locally: ",[66,1217,1218],{},"kg-html-to-lexical"," 1.4.1 and ",[66,1221,1222],{},"kg-lexical-html-renderer"," 1.5.1. The sample included a nested list, a comparison table, indented code, a figure caption and a relative link.",[11,1225,1226,1227,1231],{},"All five survived the comparison. The table became an HTML card; the list, code and image used their corresponding content nodes. The ",[15,1228,1230],{"href":1229},"\u002Fexamples\u002Fmove-ai-draft-into-cms\u002Fexample.html","source and runnable test"," show exactly what we compared. This tests those libraries with that input; your CMS editor and theme still need their own preview check.",[11,1233,1234],{},"That distinction matters during repair. Preserving a fragment as HTML may keep the markup you need, while changing how an editor can work on it.",[23,1236,1238],{"id":1237},"how-do-i-spot-and-repair-a-conversion-loss","How do I spot and repair a conversion loss?",[11,1240,1241],{},"Compare the source with the output, then change the smallest part responsible for the mismatch. Reconvert from the saved source so you can tell whether the repair worked.",[11,1243,1244,1245,1248,1249,1252,1253,1256],{},"Our source had a heading with ",[66,1246,1247],{},"id=\"conversion-checks\""," and a link to ",[66,1250,1251],{},"#conversion-checks",". Conversion regenerated the heading's ID from its text: ",[66,1254,1255],{},"move-a-reviewed-draft-into-the-cms",". The link kept its old destination. The words were still there; the destination was gone.",[11,1258,1259],{},"Ghost documents HTML-card markers for preserving supplied HTML. Wrapping just the heading kept its original ID in our rerun:",[689,1261,1266],{"className":1262,"code":1264,"language":1265,"meta":326},[1263],"language-html","\u003C!--kg-card-begin: html-->\n\u003Ch2 id=\"conversion-checks\">Move a reviewed draft into the CMS\u003C\u002Fh2>\n\u003C!--kg-card-end: html-->\n","html",[66,1267,1264],{"__ignoreMap":326},[11,1269,1270,1271,807,1275,1279,1280,1284],{},"The unchanged link then had a target again, and the other five checks still passed. You can inspect the ",[15,1272,1274],{"href":1273},"\u002Fexamples\u002Fmove-ai-draft-into-cms\u002Fexample.html#original","original",[15,1276,1278],{"href":1277},"\u002Fexamples\u002Fmove-ai-draft-into-cms\u002Fexample.html#converted","converted"," and ",[15,1281,1283],{"href":1282},"\u002Fexamples\u002Fmove-ai-draft-into-cms\u002Fexample.html#repaired","repaired"," samples.",[11,1286,1287],{},"Keeping the old ID is useful when existing links depend on it. If no link depends on that ID, updating the link to the new destination may be enough. Check that choice against the article's actual links before adding a preservation workaround.",[23,1289,1291],{"id":1290},"what-should-i-check-beyond-how-the-preview-looks","What should I check beyond how the preview looks?",[11,1293,1294],{},"Use the content. Follow a nested procedure, read the table by its headers, copy the code and open the links. These checks reveal changes a visual skim can miss.",[228,1296,1297,1303,1309,1315,1321],{},[141,1298,1299,1302],{},[31,1300,1301],{},"Lists:"," confirm a substep still belongs to the step that controls it. A flattened list can change the order of work.",[141,1304,1305,1308],{},[31,1306,1307],{},"Tables:"," check that each value has the right header and that the last column is reachable on a narrow screen.",[141,1310,1311,1314],{},[31,1312,1313],{},"Code:"," copy it from the preview into a plain-text editor and compare the characters and indentation with the source. Run it only in an appropriate test environment.",[141,1316,1317,1320],{},[31,1318,1319],{},"Figures:"," confirm the image loads and its caption and alternative text still describe the right thing.",[141,1322,1323,1326,1327,1330],{},[31,1324,1325],{},"Links:"," check the resolved destination, including in-page anchors. A relative link such as ",[66,1328,1329],{},"..\u002Fpublishing-checks\u002F"," depends on where the new article lives, even if conversion leaves its text untouched.",[11,1332,1333],{},"Inspect the draft at desktop and phone widths. Keep ordinary paragraphs within the page; give genuinely wide code or tables a usable scrolling area. A browser's developer tools can help distinguish a missing element from one hidden by styling.",[23,1335,1337],{"id":1336},"when-is-the-converted-draft-ready-for-publication","When is the converted draft ready for publication?",[11,1339,1340],{},"When it preserves the approved meaning, the required structures work, and the preview has passed those checks in the destination's actual theme. Save the corrected CMS draft and compare it once more after saving.",[11,1342,1343],{},"Keep the approved source, the CMS draft identifier and a brief note of any deliberate conversion repairs together. The person publishing it should be able to tell which draft passed review and why its markup differs from the source.",[11,1345,1346],{},"If a necessary structure still fails, leave that draft unpublished and resolve the specific mismatch. Approval belongs to the version you checked.",{"title":326,"searchDepth":327,"depth":327,"links":1348},[1349,1350,1351,1352,1353],{"id":1190,"depth":327,"text":1191},{"id":1208,"depth":327,"text":1209},{"id":1237,"depth":327,"text":1238},{"id":1290,"depth":327,"text":1291},{"id":1336,"depth":327,"text":1337},"Keep the approved source, compare the converted draft, and repair what changed. A small Ghost conversion test shows why working links matter as much as appearance.",{},"\u002Farticles\u002Fmove-ai-draft-into-cms",[347,587],[1359,350],"make-dense-ai-guide-easier-to-use",[353],"Move an AI-assisted draft into a CMS while preserving structure, code, captions and working links",{"title":1173,"description":1354},"articles\u002Fmove-ai-draft-into-cms",[1365,1366,1367,858],"CMS","content conversion","Ghost","hkn67gU-ov5yqAWXCHiZrY36CLUpfbOz3f1bHpRfLAE",{"id":1370,"title":1371,"author":6,"body":1372,"category":843,"description":1591,"extension":336,"featured":337,"heroImage":338,"meta":1592,"navigation":340,"path":1593,"publishedAt":361,"readingTime":585,"relatedAgents":1594,"relatedArticles":1595,"relatedWorkflows":1597,"searchIntent":1598,"seo":1599,"stem":1600,"topics":1601,"updatedAt":1605,"visual":362,"__hash__":1606},"articles\u002Farticles\u002Fsolved-support-tickets-to-troubleshooting-guide.md","How do I turn solved support tickets into a troubleshooting guide?",{"type":8,"value":1373,"toc":1581},[1374,1383,1386,1390,1393,1396,1399,1438,1446,1450,1453,1468,1471,1479,1483,1486,1489,1494,1497,1501,1504,1507,1512,1519,1553,1556,1568,1572,1575,1578],[11,1375,1376,1377,1382],{},"Extract the diagnosis and verified fix, state when it applies, and check whether an existing guide already covers it. ",[15,1378,1381],{"href":1379,"rel":1380},"https:\u002F\u002Fsupport.zendesk.com\u002Fhc\u002Fen-us\u002Farticles\u002F9409324793498-Creating-help-center-content-using-ticket-data-and-generative-AI",[19],"Zendesk warns"," that its feature for generating a help center from tickets can create duplicate sections and categories when a well-maintained help center already exists.",[11,1384,1385],{},"The other trap is grouping tickets by the error message. Three people can report “export failed” while one of them needs a different fix. The useful part of the guide is the check that tells that reader which situation they are in.",[23,1387,1389],{"id":1388},"which-parts-of-a-solved-ticket-are-useful-to-the-next-reader","Which parts of a solved ticket are useful to the next reader?",[11,1391,1392],{},"Keep the symptom, relevant environment, diagnostic evidence, confirmed cause, fix and observed result. Preserve the conditions that made the fix work, including the product version or configuration when they matter.",[11,1394,1395],{},"Use cleared case details and remove private identifiers from the public explanation. An account name may be unnecessary; the fact that the account had a particular permission may determine whether the instructions apply. Keep the supporting ticket reference with the internal evidence so an editor can trace the claim without publishing the conversation.",[11,1397,1398],{},"For this article, we created and ran three synthetic cases with a small Python program that copies a CSV to a configured destination:",[228,1400,1401,1415,1426],{},[141,1402,1403,1406,1407,1410,1411,1414],{},[31,1404,1405],{},"Case A:"," export failed at ",[66,1408,1409],{},"reports\u002Fweekly.csv",". The input existed, but the ",[66,1412,1413],{},"reports"," directory did not.",[141,1416,1417,1406,1420,1410,1423,1414],{},[31,1418,1419],{},"Case B:",[66,1421,1422],{},"exports\u002Fmonthly.csv",[66,1424,1425],{},"exports",[141,1427,1428,1406,1431,1434,1435,190],{},[31,1429,1430],{},"Case C:",[66,1432,1433],{},"data\u002Fsources.csv",". The destination directory existed; the configuration named the wrong input file. The prepared file was ",[66,1436,1437],{},"data\u002Fsource.csv",[11,1439,1440,1441,1445],{},"All three returned “No such file or directory.” The ",[15,1442,1444],{"href":1443},"\u002Fexamples\u002Fsolved-support-tickets-to-troubleshooting-guide\u002Fexample.html","case records and runnable example"," retain the exact paths, setup and results. These are invented support cases with observed local behavior; no customer tickets were used.",[23,1447,1449],{"id":1448},"when-should-similar-tickets-become-one-guide","When should similar tickets become one guide?",[11,1451,1452],{},"Combine cases when the same diagnostic conditions justify the same action. A and B belong together because their input files exist and their intended destination directories are missing. Their different folder names do not change the diagnosis.",[11,1454,1455,1456,1460,1461,1464,1465],{},"C belongs in the guide's exclusion branch: check the input before creating a destination directory. The ",[15,1457,1459],{"href":1458},"\u002Fexamples\u002Fsolved-support-tickets-to-troubleshooting-guide\u002Fgrouping.md","grouping sheet"," records that decision. A title such as ",[31,1462,1463],{},"“Export fails because its destination directory is missing”"," fits the supported fix better than ",[31,1466,1467],{},"“Fix all export errors.”",[11,1469,1470],{},"Search your existing help content for the reader's task, error and relevant conditions. If a guide already covers this diagnosis, add the missing check or example there. If another article owns a different cause, link to its diagnostic branch instead of copying its procedure. Create a new article when the reader question still lacks an adequate answer.",[11,1472,1473,1474,1478],{},"An unresolved cause needs investigation before it can become a confident instruction. The ",[15,1475,1477],{"href":1476},"\u002Flibrary\u002Farticles\u002Fhow-to-separate-issue-investigation-from-implementation\u002F","issue-investigation guide"," explains how to preserve observations and uncertainty when further work is needed.",[23,1480,1482],{"id":1481},"how-do-i-stop-the-guide-from-recommending-the-wrong-fix","How do I stop the guide from recommending the wrong fix?",[11,1484,1485],{},"Put the diagnostic check before the action and say which result rules that action out. “This worked in two tickets” is insufficient when the third ticket fails for another reason.",[11,1487,1488],{},"Here is the overgeneralized instruction we rejected:",[42,1490,1491],{},[11,1492,1493],{},"If export says “No such file or directory,” create its output directory and rerun.",[11,1495,1496],{},"That skips the input-file check. In C, the exporter cannot read its configured input, and its output directory already exists. Creating a directory cannot correct that input mismatch. The replacement must check the input before offering the directory fix.",[23,1498,1500],{"id":1499},"what-does-a-reproducible-troubleshooting-section-contain","What does a reproducible troubleshooting section contain?",[11,1502,1503],{},"Give the reader the applicable setup, a diagnostic check, the action that follows from it, the expected result and a stopping point. Keep each condition beside the step it controls.",[11,1505,1506],{},"Here is the finished section for someone using the sample exporter:",[1508,1509,1511],"h3",{"id":1510},"export-fails-because-its-destination-directory-is-missing","Export fails because its destination directory is missing",[11,1513,1514,1515,1518],{},"Use these steps with the sample CSV exporter when it reports “No such file or directory.” Start in the folder containing its ",[66,1516,1517],{},"config.json","; the configured paths are relative to that folder.",[138,1520,1521,1534,1544],{},[141,1522,1523,1526,1527,1529,1530,1533],{},[31,1524,1525],{},"Check the input file."," Open ",[66,1528,1517],{}," and read the ",[66,1531,1532],{},"input"," path. Confirm that it points to an existing file. If the file is absent, stop and ask the export owner to confirm the intended source; do not guess a replacement filename.",[141,1535,1536,1539,1540,1543],{},[31,1537,1538],{},"Check the destination."," Read the ",[66,1541,1542],{},"output"," path and confirm that it is where you intend to save the export. Check the folder that would contain that file. If the folder already exists, stop: this missing-directory procedure does not establish the cause.",[141,1545,1546,1549,1550,1552],{},[31,1547,1548],{},"Create the confirmed missing folder and rerun the exporter."," Open the resulting file at the configured ",[66,1551,1542],{}," path and compare its contents with the input file. They should match exactly.",[11,1554,1555],{},"If the export still fails or the contents differ, stop and give the export owner the configuration and exact error or mismatch. Creating the folder alone does not mean the export is fixed.",[11,1557,1558,1559,1279,1563,1567],{},"The companion provides ",[15,1560,1562],{"href":1561},"\u002Fexamples\u002Fsolved-support-tickets-to-troubleshooting-guide\u002Fexample.html#run","setup instructions",[15,1564,1566],{"href":1565},"\u002Fexamples\u002Fsolved-support-tickets-to-troubleshooting-guide\u002Fexample.html#manual","manual commands"," to run this procedure from a clean starting point, including the file-content comparison.",[23,1569,1571],{"id":1570},"how-do-i-know-the-finished-guide-is-ready","How do I know the finished guide is ready?",[11,1573,1574],{},"Have someone who did not write it follow the instructions from a clean setup, including a case where the fix must be rejected. Compare their observations with the stated results, then review the public text against its source evidence and disclosure limits.",[11,1576,1577],{},"In the independent check, A and B produced files identical to their sources, while the input check stopped C before a directory repair.",[11,1579,1580],{},"Before finalizing your article, trace each instruction to the cases that support it. Check that the product version and necessary permissions are clear, private details are removed, and unexpected results have a useful next step. Keep the tests and source mapping with the maintained guide so a later product change gives the editor something concrete to recheck.",{"title":326,"searchDepth":327,"depth":327,"links":1582},[1583,1584,1585,1586,1590],{"id":1388,"depth":327,"text":1389},{"id":1448,"depth":327,"text":1449},{"id":1481,"depth":327,"text":1482},{"id":1499,"depth":327,"text":1500,"children":1587},[1588],{"id":1510,"depth":1589,"text":1511},3,{"id":1570,"depth":327,"text":1571},"Group solved cases by diagnosis, preserve the conditions behind each fix, and test the guide against a similar case where that fix should be rejected.",{},"\u002Farticles\u002Fsolved-support-tickets-to-troubleshooting-guide",[346,587,347],[1596,350],"how-to-separate-issue-investigation-from-implementation",[353],"Turn resolved support cases into accurate public troubleshooting instructions with diagnostic checks, applicability limits and verified results",{"title":1371,"description":1591},"articles\u002Fsolved-support-tickets-to-troubleshooting-guide",[1602,1603,1604,858],"support documentation","troubleshooting","knowledge bases","2026-10-08","njrXD-zGkaxdq2FBo6AIOQGqf1eYHgkC48cN_gexWX8",{"id":1608,"title":1609,"author":6,"body":1610,"category":843,"description":1830,"extension":336,"featured":337,"heroImage":338,"meta":1831,"navigation":340,"path":1832,"publishedAt":361,"readingTime":585,"relatedAgents":1833,"relatedArticles":1834,"relatedWorkflows":1837,"searchIntent":1838,"seo":1839,"stem":1840,"topics":1841,"updatedAt":361,"visual":362,"__hash__":1845},"articles\u002Farticles\u002Fverify-approved-article-is-published.md","How do I verify that the approved article is actually published?",{"type":8,"value":1611,"toc":1823},[1612,1637,1640,1644,1647,1650,1675,1678,1686,1690,1693,1707,1715,1719,1722,1725,1748,1755,1768,1771,1775,1778,1793,1802,1805,1809,1812,1820],[11,1613,1614,1615,1620,1621,807,1624,807,1627,807,1630,1633,1634,190],{},"Open the intended public URL without editor access and compare the article with the exact version that passed review. ",[15,1616,1619],{"href":1617,"rel":1618},"https:\u002F\u002Fdeveloper.wordpress.org\u002Frest-api\u002Freference\u002Fposts\u002F",[19],"WordPress's posts schema"," defines a post's ID separately from its status, which can be ",[66,1622,1623],{},"publish",[66,1625,1626],{},"future",[66,1628,1629],{},"draft",[66,1631,1632],{},"pending"," or ",[66,1635,1636],{},"private",[11,1638,1639],{},"A publishing response is useful evidence. So is a preview. The remaining check is whether a reader receives the approved words at the intended address.",[23,1641,1643],{"id":1642},"which-approved-version-and-destination-am-i-checking","Which approved version and destination am I checking?",[11,1645,1646],{},"Start with the saved version named in the approval and the URL where it should appear. “The latest draft” is too loose if someone edited it after review.",[11,1648,1649],{},"Keep a short verification note beside that source:",[228,1651,1652,1658,1664,1670],{},[141,1653,1654,1657],{},[31,1655,1656],{},"Version:"," the approved file, revision or content fingerprint.",[141,1659,1660,1663],{},[31,1661,1662],{},"Destination:"," the intended public URL and the CMS post or deployment it belongs to.",[141,1665,1666,1669],{},[31,1667,1668],{},"Audience and time:"," who should be able to read it, and when it should become available.",[141,1671,1672,1674],{},[31,1673,1114],{}," the preview URL, time of the public check and any differences found.",[11,1676,1677],{},"Pick a substantive passage to inspect closely, especially one changed in the approved revision. The title alone may be identical in both versions. For a larger article, also review the other changed passages, links and media; one matching sentence cannot establish that the whole article agrees.",[11,1679,1680,1681,1685],{},"If the text is already wrong in the draft preview, return to the ",[15,1682,1684],{"href":1683},"\u002Flibrary\u002Farticles\u002Fmove-ai-draft-into-cms\u002F","conversion check"," before investigating public delivery.",[23,1687,1689],{"id":1688},"what-does-the-cms-response-prove","What does the CMS response prove?",[11,1691,1692],{},"Read the identifier, state and destination separately. The ID locates a record; its status tells you what state the CMS reports. Inspect the schedule and visibility settings when they apply, then check the supplied public link against your intended destination.",[11,1694,1695,1696,1699,1700,1702,1703,1706],{},"For this article, we ran a small synthetic website locally. Its mock CMS returned post ID ",[66,1697,1698],{},"42",", status ",[66,1701,1623],{}," and link ",[66,1704,1705],{},"\u002Fweekly-report\u002F",". Those fields all looked consistent with publication, and its preview contained the approved article.",[11,1708,1709,1710,1714],{},"The public page still contained an old instruction. The ",[15,1711,1713],{"href":1712},"\u002Fexamples\u002Fverify-approved-article-is-published\u002Fexample.html","runnable example and recorded responses"," keep that synthetic record and the actual HTTP reads together.",[23,1716,1718],{"id":1717},"how-do-i-check-what-a-public-reader-actually-receives","How do I check what a public reader actually receives?",[11,1720,1721],{},"Open the exact destination with the intended audience's access, confirm where the browser lands, and compare the body with the approved source. For a public article, use a session without editor credentials. For restricted content, use an account with the reader's actual permissions.",[11,1723,1724],{},"Our example article explains how to export a weekly report. Its comparison was small enough to inspect directly:",[228,1726,1727,1736,1742],{},[141,1728,1729,1735],{},[31,1730,1731,1732,687],{},"Approved revision ",[66,1733,1734],{},"weekly-report-v2"," “Select Last seven days before exporting.”",[141,1737,1738,1741],{},[31,1739,1740],{},"Preview:"," the same approved instruction.",[141,1743,1744,1747],{},[31,1745,1746],{},"Public response:"," “Select All dates before exporting.”",[11,1749,1750,1751,1754],{},"The public request returned HTTP ",[66,1752,1753],{},"200",". The title, help link and inline image also matched the approved source. The wrong date-range instruction was the difference that mattered to someone following the guide.",[11,1756,1757,1758,1762,1763,1767],{},"You can open the saved ",[15,1759,1761],{"href":1760},"\u002Fexamples\u002Fverify-approved-article-is-published\u002Fview-source-preview.html","source and preview comparison"," and the ",[15,1764,1766],{"href":1765},"\u002Fexamples\u002Fverify-approved-article-is-published\u002Fview-public-before.html","initial public response",". The test made its HTTP reads without cookies or authorization against a server on the same machine. It demonstrates the content comparison; a real site's audience access needs checking at that site's public address.",[11,1769,1770],{},"On your page, follow the important links and confirm that the right images load, too. Read the changed text in context: a matching sentence under the wrong heading or beside an obsolete screenshot can still mislead the reader. Record the actual discrepancy rather than reducing the result to “page opened.”",[23,1772,1774],{"id":1773},"what-if-the-preview-is-right-but-the-public-article-is-stale","What if the preview is right but the public article is stale?",[11,1776,1777],{},"Locate where the versions diverge before choosing a correction. Check that you opened the right URL, that the intended revision was published, and that its schedule and visibility match the request. If those agree, inspect the site or hosting layer serving the old body.",[11,1779,1780,1781,1784,1785,1787,1788,1792],{},"In our test, we deliberately initialized a small local cache with the old article. Clearing that cache and reading ",[31,1782,1783],{},"the same public URL"," again returned HTTP ",[66,1786,1753],{}," with “Select Last seven days before exporting.” The ",[15,1789,1791],{"href":1790},"\u002Fexamples\u002Fverify-approved-article-is-published\u002Fview-public-after.html","corrected response"," matched the approved HTML and preview; the title, link and inline image stayed unchanged.",[11,1794,1795,1796,1801],{},"That correction cleared only the example's cache. On a real site, use the relevant CMS or host's supported correction, then repeat the public comparison. ",[15,1797,1800],{"href":1798,"rel":1799},"https:\u002F\u002Fdeveloper.mozilla.org\u002Fen-US\u002Fdocs\u002FWeb\u002FHTTP\u002FReference\u002FHeaders\u002FCache-Control",[19],"MDN's cache documentation"," distinguishes browser caches from shared caches between the browser and server. Opening a private window does not establish that an intermediate cache was cleared.",[11,1803,1804],{},"Record the second observation alongside the first. The correction is verified when the expected content appears at the intended destination for the audience you checked.",[23,1806,1808],{"id":1807},"what-should-i-do-when-the-result-is-still-uncertain","What should I do when the result is still uncertain?",[11,1810,1811],{},"Keep the publication check open and name the missing evidence. Inspect the existing post, deployment or request before attempting another write; a lost response does not tell you whether the first attempt succeeded.",[11,1813,1814,1815,1819],{},"A useful handoff says which version was approved, which destination was checked, what appeared there and what still needs resolving. Attach the relevant response or passage and give the next check an owner. The ",[15,1816,1818],{"href":1817},"\u002Flibrary\u002Farticles\u002Fwhat-ai-agent-handoff-should-include\u002F","agent handoff guide"," works through that decision after an interrupted update.",[11,1821,1822],{},"If the public body still says “All dates,” report that exact mismatch. Another “publish succeeded” message would leave the reader with the same wrong instruction.",{"title":326,"searchDepth":327,"depth":327,"links":1824},[1825,1826,1827,1828,1829],{"id":1642,"depth":327,"text":1643},{"id":1688,"depth":327,"text":1689},{"id":1717,"depth":327,"text":1718},{"id":1773,"depth":327,"text":1774},{"id":1807,"depth":327,"text":1808},"Compare the approved article with the version readers receive. A small publication check shows how a correct preview and a successful response can still hide an old instruction.",{},"\u002Farticles\u002Fverify-approved-article-is-published",[587,347],[1835,1836],"move-ai-draft-into-cms","what-ai-agent-handoff-should-include",[353],"Verify that the approved article version is available at the intended public URL and diagnose a mismatch between the preview and public page",{"title":1609,"description":1830},"articles\u002Fverify-approved-article-is-published",[1842,1365,1843,1844],"publishing","content verification","AI workflows","up8EIKnc7YmyzxNMWTZ-dG3irPcI5USCBKzAoPbIAKI",{"id":1847,"title":1848,"author":6,"body":1849,"category":334,"description":2072,"extension":336,"featured":337,"heroImage":338,"meta":2073,"navigation":340,"path":2074,"publishedAt":342,"readingTime":343,"relatedAgents":2075,"relatedArticles":2078,"relatedWorkflows":2080,"searchIntent":2081,"seo":2082,"stem":2083,"topics":2084,"updatedAt":361,"visual":362,"__hash__":2088},"articles\u002Farticles\u002Fchoose-pages-to-improve-with-search-console.md","Which page should I improve first using Search Console data?",{"type":8,"value":1850,"toc":2065},[1851,1860,1864,1867,1870,1875,1878,1881,1902,1910,1914,1917,1937,1940,1943,1948,1951,1960,1964,1967,1974,1991,1994,2001,2005,2013,2020,2025,2028,2034,2040,2046,2049,2052,2056,2059,2062],[11,1852,1853,1854,1859],{},"Start with a page that answers a useful customer question but leaves a clear gap you can fix, then use its query and page data to compare it with the alternatives. ",[15,1855,1858],{"href":1856,"rel":1857},"https:\u002F\u002Fdevelopers.google.com\u002Fwebmaster-tools\u002Fv1\u002Fsearchanalytics\u002Fquery",[19],"Search Console's API"," returns top rows rather than every row, so a missing query is not evidence that nobody searches for it.",[23,1861,1863],{"id":1862},"what-reader-problem-would-improving-this-page-solve","What reader problem would improving this page solve?",[11,1865,1866],{},"Name the decision your intended customer needs to make, then read the page's instructions. “Get more traffic” gives you no way to distinguish a useful visitor from someone looking for a product you do not sell.",[11,1868,1869],{},"Consider a fictional software company whose customers review workflow runs, assign someone to handle a failure and export audit logs. Its readers are operations managers. One guide, P1, explains how to find failed runs, then says:",[42,1871,1872],{},[11,1873,1874],{},"Start with the oldest failed run and work down the list.",[11,1876,1877],{},"The next instruction is to correct the input and retry. Following that advice, someone could spend the morning fixing an old internal summary while a customer's onboarding remains blocked. The page never explains how to compare the consequences of two failures. That is a gap an editor can name and repair.",[11,1879,1880],{},"The company also has guides defining a task queue (P2), finding approval delays (P3) and exporting an audit log (P4). We will compare all four before choosing the work.",[11,1882,1883,1884,1888,1889,807,1893,1279,1897,1901],{},"The company, page bodies and figures in this exercise are invented. The ",[15,1885,1887],{"href":1886},"\u002Fexamples\u002Fchoose-pages-to-improve-with-search-console\u002Fquery-page-data.csv","twelve-row CSV"," uses September 1–28, 2026, Pacific time; United States; web search; all devices; finalized data. These are selected query\u002Fpage pairs, not complete page totals. The ",[15,1890,1892],{"href":1891},"\u002Fexamples\u002Fchoose-pages-to-improve-with-search-console\u002Fpage-snapshots.md","four page bodies",[15,1894,1896],{"href":1895},"\u002Fexamples\u002Fchoose-pages-to-improve-with-search-console\u002Fdecision-sheet.md","completed decision sheet",[15,1898,1900],{"href":1899},"\u002Fexamples\u002Fchoose-pages-to-improve-with-search-console\u002Freport-scope.json","report settings"," supply the full exercise.",[11,1903,1904,1905,1909],{},"For your own comparison, keep the date range and filters with the export. The ",[15,1906,1908],{"href":1907},"\u002Flibrary\u002Fintegrations\u002Fgoogle-search-console\u002F","Search Console guide"," covers getting a report; the decision here starts after you have one.",[23,1911,1913],{"id":1912},"which-queries-belong-to-the-same-reader-task","Which queries belong to the same reader task?",[11,1915,1916],{},"Group queries when a useful answer would let those readers do the same thing. Three supplied rows point to P1:",[228,1918,1919,1925,1931],{},[141,1920,1921,1924],{},[31,1922,1923],{},"Q01:"," “how to prioritize failed automated tasks” — 8 clicks from 320 impressions.",[141,1926,1927,1930],{},[31,1928,1929],{},"Q02:"," “which workflow failures should i fix first” — 3 clicks from 120 impressions.",[141,1932,1933,1936],{},[31,1934,1935],{},"Q03:"," “workflow error triage checklist” — 4 clicks from 80 impressions.",[11,1938,1939],{},"All three ask how to choose which failed work needs attention first. P1's oldest-first instruction does not answer that decision. Counting words or treating each phrase as a new article would split one useful answer into three jobs.",[11,1941,1942],{},"P2's queries point in different directions: “python task queue,” “task queue” and “workflow exception handoff template.” Those readers may want a library, a definition or instructions for passing failed work to another person. The page supplies a definition and ends with:",[42,1944,1945],{},[11,1946,1947],{},"You can assign a failed task to another teammate when it needs their attention.",[11,1949,1950],{},"That leaves the handoff reader to work out what information to send. The Python reader has found the wrong company: this business does not sell a Python library. The phrase “task queue” cannot settle either problem.",[11,1952,1953,1954,1959],{},"In a real report, ",[15,1955,1958],{"href":1956,"rel":1957},"https:\u002F\u002Fsupport.google.com\u002Fwebmasters\u002Fanswer\u002F17010961",[19],"filter to a query and inspect the Pages tab"," to see which URLs appeared for it. Then read their answers; the report cannot tell you whether they are useful.",[23,1961,1963],{"id":1962},"why-might-the-largest-impression-count-point-to-the-wrong-work","Why might the largest impression count point to the wrong work?",[11,1965,1966],{},"The largest row here is Q04, “python task queue,” with 4,200 impressions. Its audience mismatch gives us no reason to expand P2 in that direction.",[11,1968,1969,1970,1973],{},"Q06, the handoff-template query, suggests more useful work: ",[31,1971,1972],{},"consider a separate handoff guide",". It could show the failed task, what already happened, the customer consequence, the next check and a named owner. Before commissioning it, check that no existing page answers the question and that the product supports those instructions. Keep P2's definition focused.",[11,1975,1976,1977,1980,1981,1986,1987,1990],{},"For P3, ",[31,1978,1979],{},"investigate the reader's task",". “Workflow approval wait time report” has a 25% CTR, but that is one click from four impressions. Google defines ",[15,1982,1985],{"href":1983,"rel":1984},"https:\u002F\u002Fsupport.google.com\u002Fwebmasters\u002Fanswer\u002F7042828",[19],"CTR as clicks divided by impressions","; the companion CSV stores it as a fraction, so ",[66,1988,1989],{},"0.25"," means 25%.",[11,1992,1993],{},"The stronger question comes from the page itself. P3 explains how to check one request: find its approver, look for missing decision material and ask what is holding it up. A report comparing delays across many requests needs a different explanation. A concrete customer question and available product data could justify that guide even with few impressions. Another comparable reporting period may help, but an arbitrary minimum count cannot choose the task for us.",[11,1995,1996,1997,2000],{},"P3 is the strongest unresolved alternative. ",[31,1998,1999],{},"Refresh P1 first"," because its relevant question, deficient passage and feasible repair are already clear. P4 has a reason to wait too, which we will check against its actual instructions below.",[23,2002,2004],{"id":2003},"what-exact-change-would-make-the-selected-page-more-useful","What exact change would make the selected page more useful?",[11,2006,2007,2008,2012],{},"Replace P1's oldest-first instruction with a way to compare consequences, then show how that changes the next action. This is a bounded ",[15,2009,2011],{"href":2010},"\u002Flibrary\u002Fworkflows\u002Fseo-content-refresh\u002F","content refresh",": the page keeps its purpose and gains the decision its readers are asking for.",[11,2014,2015,2016,2019],{},"The selected URL is ",[66,2017,2018],{},"https:\u002F\u002Fexample.com\u002Fguides\u002Freview-workflow-errors\u002F",". A replacement paragraph could say:",[42,2021,2022],{},[11,2023,2024],{},"Check what each failure is blocking and when that work is needed. Look for failures with a shared cause before treating each row as a separate fix. Read what the previous attempt already did before retrying it. If you cannot establish the next action, assign an owner and write down what they need to check.",[11,2026,2027],{},"Then give the reader three cases:",[11,2029,2030,2033],{},[31,2031,2032],{},"Customer onboarding is blocked."," Account creation stopped before it completed, so the customer cannot continue. Assign an owner to diagnose the block and confirm how to resume.",[11,2035,2036,2039],{},[31,2037,2038],{},"An internal summary can wait."," The daily summary failed, but nobody needs it until tomorrow. Schedule it behind the current customer block.",[11,2041,2042,2045],{},[31,2043,2044],{},"A notification's outcome is unknown."," The attempt timed out. Check whether the notification arrived before deciding to send another.",[11,2047,2048],{},"Those assumptions matter. If the summary is needed for a deadline this morning and the customer has a working manual route, the order changes. Product-specific recovery steps also need checking against the product before publication.",[11,2050,2051],{},"Ask someone who did not write the revision to choose the next action in these cases, including the deadline variation. If they still default to the oldest row, the explanation needs work. Keep the selected URL, old passage, replacement and report scope in the decision sheet, and record the edit date for later comparison. Whether traffic changes is a separate observation.",[23,2053,2055],{"id":2054},"what-evidence-would-justify-leaving-a-page-alone","What evidence would justify leaving a page alone?",[11,2057,2058],{},"An accurate, findable answer to the relevant task is a reason to leave it alone. P4 gives the export path, permissions and date controls. It says “Timestamps use UTC” and explains that successful and failed runs are included unless a status filter excludes them. It even tells the reader to find a known failed run in the CSV to check the export.",[11,2060,2061],{},"Those passages answer Q10–Q12. Q12's average position of 8.6 does not identify a missing explanation. Neither would selecting every query in a position band of 5–20. You still need to name what a reader cannot understand or do.",[11,2063,2064],{},"A changed interface, an incorrect field or evidence that readers cannot find the timezone answer would reopen P4. For now, the useful work is on P1.",{"title":326,"searchDepth":327,"depth":327,"links":2066},[2067,2068,2069,2070,2071],{"id":1862,"depth":327,"text":1863},{"id":1912,"depth":327,"text":1913},{"id":1962,"depth":327,"text":1963},{"id":2003,"depth":327,"text":2004},{"id":2054,"depth":327,"text":2055},"Compare four pages using Search Console queries and their actual content. Choose one useful edit with a worked CSV, page examples and completed decision sheet.",{},"\u002Farticles\u002Fchoose-pages-to-improve-with-search-console",[2076,2077],"seo-workflow-content-refresh","seo-workflow-keyword-research",[2079],"how-to-do-keyword-research-for-ai-search",[1161,352],"Choose which existing page to improve using query and page evidence, business relevance and an inspected answer gap",{"title":1848,"description":2072},"articles\u002Fchoose-pages-to-improve-with-search-console",[2085,2086,2087],"Search Console","content prioritization","SEO content refresh","nHbJoPiOq1SolhrLMcOlUkBHKe0MfWLUqSbUgQqaKFI",{"id":2090,"title":2091,"author":6,"body":2092,"category":334,"description":2489,"extension":336,"featured":337,"heroImage":338,"meta":2490,"navigation":340,"path":2491,"publishedAt":342,"readingTime":2492,"relatedAgents":2493,"relatedArticles":2496,"relatedWorkflows":2498,"searchIntent":2501,"seo":2502,"stem":2503,"topics":2504,"updatedAt":361,"visual":362,"__hash__":2508},"articles\u002Farticles\u002Fprioritize-technical-seo-audit-findings.md","Which technical SEO audit findings should I fix first?",{"type":8,"value":2093,"toc":2482},[2094,2103,2107,2114,2117,2120,2126,2132,2144,2153,2156,2195,2216,2220,2223,2244,2247,2254,2263,2266,2270,2273,2345,2348,2358,2362,2374,2383,2389,2392,2457,2466,2470,2473,2476,2479],[11,2095,2096,2097,2102],{},"Start with confirmed problems that block access to important pages or break a useful journey, then group repeated warnings by their shared cause. ",[15,2098,2101],{"href":2099,"rel":2100},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Fmonitor-debug\u002Fdebugging-search-traffic-drops",[19],"Google's troubleshooting guidance"," distinguishes site-wide technical failures from page-specific ones, so the number of warnings alone cannot tell you the size of the problem.",[23,2104,2106],{"id":2105},"is-this-warning-a-demonstrated-defect-or-a-tools-heuristic","Is this warning a demonstrated defect or a tool's heuristic?",[11,2108,2109,2110,2113],{},"Reproduce what the warning describes and compare it with the page's intended behavior. A scanner can correctly detect ",[66,2111,2112],{},"noindex"," while leaving the most important question unanswered: should this page appear in search?",[11,2115,2116],{},"Take this invented audit of a software website. All URLs, responses, code fragments and diagnostic observations below are fictional teaching material; no audit or repair was performed on StackOS or a customer site.",[11,2118,2119],{},"Three public integration pages contain:",[689,2121,2124],{"className":2122,"code":2123,"language":1265,"meta":326},[1263],"\u003Cmeta name=\"robots\" content=\"noindex, follow\">\n",[66,2125,2123],{"__ignoreMap":326},[11,2127,2128,2129,2131],{},"So does the site's internal search-results page. The operator wants the integrations eligible for search and deliberately excludes the utility page. Removing every ",[66,2130,2112],{}," would fix one problem and create another.",[11,2133,2134,2135,2143],{},"The directive needs to be understood in context. Google must be able to ",[15,2136,2139,2140,2142],{"href":2137,"rel":2138},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Fcrawling-indexing\u002Fblock-indexing",[19],"crawl a page to read its ",[66,2141,2112],{}," instruction",". In this exercise, both page types are crawlable. The utility contains public links; its exclusion is a search policy, not protection for private information.",[11,2145,2146,2147,2152],{},"The audit also calls a product description “too short” because it is under the scanner's invented 120-character minimum. The text accurately describes the page. Google's ",[15,2148,2151],{"href":2149,"rel":2150},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Fappearance\u002Fsnippet",[19],"description guidance"," imposes no fixed length limit; displayed snippets are truncated as needed. There is no demonstrated copy defect to repair just to satisfy this rule.",[11,2154,2155],{},"Here is the complete set of twelve findings, grouped by the inspected page's template family:",[228,2157,2158,2172,2180,2186],{},[141,2159,2160,2163,2164,2167,2168,2171],{},[31,2161,2162],{},"Product:"," F01, pricing returns ",[66,2165,2166],{},"503","; F02, the trial link reaches a ",[66,2169,2170],{},"404","; F03, the description fails the length rule.",[141,2173,2174,2177,2178,190],{},[31,2175,2176],{},"Integration:"," F04–F06, three intended public pages emit ",[66,2179,2112],{},[141,2181,2182,2185],{},[31,2183,2184],{},"Guide:"," F07–F08, two unique guides declare the guide index as canonical; F09, one guide has an unexplained low lab score.",[141,2187,2188,2191,2192,2194],{},[31,2189,2190],{},"Utility:"," F10, a late widget moves the contact form; F11, search results emit intentional ",[66,2193,2112],{},"; F12, a tool flags possible unused JavaScript.",[11,2196,49,2197,2201,2202,2206,2207,1279,2211,2215],{},[15,2198,2200],{"href":2199},"\u002Fexamples\u002Fprioritize-technical-seo-audit-findings\u002Faudit-findings.csv","audit CSV"," retains every URL and finding ID. The ",[15,2203,2205],{"href":2204},"\u002Fexamples\u002Fprioritize-technical-seo-audit-findings\u002Fevidence.md","evidence file"," contains the response, page or diagnostic notes behind each one. The ",[15,2208,2210],{"href":2209},"\u002Fexamples\u002Fprioritize-technical-seo-audit-findings\u002FREADME.md","exercise notes",[15,2212,2214],{"href":2213},"\u002Fexamples\u002Fprioritize-technical-seo-audit-findings\u002Fscope.json","scope file"," explain the assumptions.",[23,2217,2219],{"id":2218},"which-warnings-share-one-template-or-underlying-cause","Which warnings share one template or underlying cause?",[11,2221,2222],{},"Group findings when their evidence points to the same repair. The repeated label is a place to start looking, but the shared implementation needs to be checked.",[11,2224,2225,2226,807,2229,1279,2232,2235,2236,2239,2240,2243],{},"The three integration pages—",[66,2227,2228],{},"\u002Fintegrations\u002Fslack\u002F",[66,2230,2231],{},"\u002Fintegrations\u002Fgoogle-drive\u002F",[66,2233,2234],{},"\u002Fintegrations\u002Fnotion\u002F","—all use an ",[66,2237,2238],{},"IntegrationPage"," template. In the supplied source, that template unconditionally sets ",[66,2241,2242],{},"robots: 'noindex, follow'",". A preview setting was copied into production. Those three warnings become one task with three affected URLs and a shared owner.",[11,2245,2246],{},"The utility search page uses a different template and has its own intentional exclusion. It belongs in the integration repair's regression checks so that an overly broad change does not remove it.",[11,2248,2249,2250,2253],{},"The two guide warnings also have one owner. Their metadata helper constructs the canonical from the constant ",[66,2251,2252],{},"\u002Fguides\u002F",", ignoring the current route. Both pages contain full, distinct answers; the destination is only a list of guide summaries. The operator's inventory identifies the individual guides as the intended canonical pages.",[11,2255,2256,2257,2262],{},"That supports correcting one helper and checking its consumers. It would not justify rewriting every canonical that points elsewhere: duplicate pages can legitimately nominate another URL. Google's ",[15,2258,2261],{"href":2259,"rel":2260},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Fcrawling-indexing\u002Fconsolidate-duplicate-urls",[19],"canonical guidance"," treats the declaration as a signal, and Google makes its own selection.",[11,2264,2265],{},"After excluding the four findings that need no immediate repair, eight accepted rows become five tasks. The arithmetic follows the demonstrated owners: three integration rows share one change, and two guide rows share another.",[23,2267,2269],{"id":2268},"which-confirmed-problem-most-affects-important-pages-or-user-journeys","Which confirmed problem most affects important pages or user journeys?",[11,2271,2272],{},"Prioritize the failure's consequence for the journeys the business needs. For this company, the operator has named reading pricing and starting a trial as immediate priorities. Both currently fail outright, so they lead the queue.",[928,2274,2275,2288],{},[931,2276,2277],{},[934,2278,2279,2282,2285],{},[937,2280,2281],{},"Order",[937,2283,2284],{},"Repair",[937,2286,2287],{},"Why it belongs here",[947,2289,2290,2301,2312,2323,2334],{},[934,2291,2292,2295,2298],{},[952,2293,2294],{},"1",[952,2296,2297],{},"Restore pricing access",[952,2299,2300],{},"The visitor cannot read the plans.",[934,2302,2303,2306,2309],{},[952,2304,2305],{},"2",[952,2307,2308],{},"Correct the trial link",[952,2310,2311],{},"“Start a trial” leads to a missing page.",[934,2313,2314,2317,2320],{},[952,2315,2316],{},"3",[952,2318,2319],{},"Correct integration indexing instructions",[952,2321,2322],{},"Three intended public pages carry an accidental exclusion.",[934,2324,2325,2328,2331],{},[952,2326,2327],{},"4",[952,2329,2330],{},"Correct guide canonical declarations",[952,2332,2333],{},"Two distinct guides nominate their index page.",[934,2335,2336,2339,2342],{},[952,2337,2338],{},"5",[952,2340,2341],{},"Stabilize the contact form",[952,2343,2344],{},"Late widget insertion moves the visible form fields.",[11,2346,2347],{},"There are no revenue figures or ranking-impact points behind that order. It follows the stated priorities and the supplied failures. An integration launch tomorrow could move the template repair up. Evidence that the contact form cannot be used would also change the decision.",[11,2349,2350,2351,2353,2354,2357],{},"Priority does not require everyone to wait for task one. The pricing route returns ",[66,2352,2166],{},", but its upstream cause remains unknown. A developer can investigate that failure while another repairs the isolated trial link. ",[15,2355,2356],{"href":1476},"Separating investigation from implementation"," matters here: the unavailable page is established, while the correct infrastructure change is still open.",[23,2359,2361],{"id":2360},"what-repair-and-acceptance-check-can-i-give-a-developer","What repair and acceptance check can I give a developer?",[11,2363,2364,2365,2369,2370,2373],{},"Give them the defect, affected URLs, bounded change and a check that could expose a bad repair. The ",[15,2366,2368],{"href":2367},"\u002Fexamples\u002Fprioritize-technical-seo-audit-findings\u002Fqueue.md","completed work queue"," holds the full reproduction and test procedures for all five tasks. All paths below belong to the fictional ",[66,2371,2372],{},"https:\u002F\u002Fexample.com\u002F"," site.",[11,2375,2376,102,2379,2382],{},[31,2377,2378],{},"Pricing is the useful worked example.",[66,2380,2381],{},"\u002Fpricing\u002F"," returns an unavailable message in three checks. The repair starts by tracing the route and its dependencies; the evidence does not yet tell us whether a configuration change or service repair will be needed.",[11,2384,2385,2386,2388],{},"“Returns ",[66,2387,1753],{},"” would be an incomplete acceptance check. A developer could serve the old error message with a success status and satisfy it. Require the original pricing link to reach the actual plans, prices and next action for an unauthenticated visitor. Retest the original failure and add a regression for the cause found. That closes the access problem the visitor experienced.",[11,2390,2391],{},"The remaining assignments can be brief:",[228,2393,2394,2415,2431,2447],{},[141,2395,2396,2399,2400,2403,2404,2407,2408,2411,2412,2414],{},[31,2397,2398],{},"Trial link:"," change the CTA on ",[66,2401,2402],{},"\u002Fproduct\u002F"," from missing ",[66,2405,2406],{},"\u002Fstart\u002F"," to the intended ",[66,2409,2410],{},"\u002Fsignup\u002F"," route. The route definition and operator support that destination. Inspect other uses before adding any redirect; accept when pointer and keyboard activation reach the usable trial form with ",[66,2413,1753],{},", and HTML and client navigation agree.",[141,2416,2417,2420,2421,2423,2424,2426,2427,2430],{},[31,2418,2419],{},"Integration exclusions:"," correct the shared production metadata for the three integration URLs named above. Check for other directives in headers or merged metadata before calling the edit complete. Each page must serve its intended content with ",[66,2422,1753],{},", permit crawling and have no applicable ",[66,2425,2112],{},"; the deliberate exclusion on ",[66,2428,2429],{},"\u002Fsearch\u002F?q=retry"," must survive.",[141,2432,2433,2436,2437,1279,2440,2443,2444,2446],{},[31,2434,2435],{},"Guide canonicals:"," fix the helper used by ",[66,2438,2439],{},"\u002Fguides\u002Fapproval-routing\u002F",[66,2441,2442],{},"\u002Fguides\u002Fworkflow-retries\u002F"," to emit their reviewed absolute URLs. Confirm aliases and normalization first. Accept consistent HTTP\u002FHTML declarations pointing to the complete ",[66,2445,1753],{}," guide, with matching internal links and sitemap entries; keep legitimate non-self canonicals elsewhere.",[141,2448,2449,2452,2453,2456],{},[31,2450,2451],{},"Contact form:"," give the late booking widget a stable, responsive space on ",[66,2454,2455],{},"\u002Fcontact\u002F",". In the supplied mobile replays, its arrival moves the email field from 208 to 568 pixels from the top. Desktop sizing and failure behavior still need checking. Accept when the insertion no longer displaces the form and both booking controls and the email fallback remain usable at the checked sizes.",[11,2458,2459,2460,2465],{},"These checks establish the repaired site behavior. Indexing and Google's canonical choice need later observation; the declarations alone cannot establish either. Likewise, ",[15,2461,2464],{"href":2462,"rel":2463},"https:\u002F\u002Fweb.dev\u002Farticles\u002Fcls",[19],"layout-shift guidance"," distinguishes lab findings from field experience. A clean widget replay does not establish a real-user performance percentile or a ranking gain.",[23,2467,2469],{"id":2468},"which-findings-should-i-defer-monitor-or-reject","Which findings should I defer, monitor or reject?",[11,2471,2472],{},"Keep findings out of implementation when the intended behavior is already correct or the evidence does not yet identify a repair. Give each one a reason and a condition that would reopen it.",[11,2474,2475],{},"F03's description warning is rejected on its length-only basis. An inaccurate promise or a demonstrated search-result problem would justify another look. F11's public search exclusion is accepted and retained as a test case for the integration change.",[11,2477,2478],{},"F09 and F12 need further investigation. The guide's 43\u002F100 lab score lacks browser settings, a trace and individual metrics. The contact page's “90 KiB potentially unused JavaScript” warning covers only initial navigation; no booking or fallback interaction was exercised. Deleting that code could remove behavior the tool never tried. Nor does fixing the form's movement establish that the bytes are unnecessary.",[11,2480,2481],{},"The next useful work is specific: rerun the guide measurement under controlled settings and inspect which metric and resource account for the delay. For the widget, capture code use while choosing a date, using the booking controls and reaching the fallback. Those observations can support a performance task with a testable outcome.",{"title":326,"searchDepth":327,"depth":327,"links":2483},[2484,2485,2486,2487,2488],{"id":2105,"depth":327,"text":2106},{"id":2218,"depth":327,"text":2219},{"id":2268,"depth":327,"text":2269},{"id":2360,"depth":327,"text":2361},{"id":2468,"depth":327,"text":2469},"Turn twelve technical SEO warnings into five justified repairs. Work through shared template causes, intentional exclusions and checks a developer can use.",{},"\u002Farticles\u002Fprioritize-technical-seo-audit-findings","8 min read",[2494,2495],"seo-workflow-website-analysis","stackos-sdlc-delivery-reviewer",[1596,2497],"how-ai-orchestrators-triage-feedback",[2499,2500],"seo-website-analysis","engineering-tracked-delivery","Prioritize technical SEO audit findings using demonstrated defects, shared causes, visitor journeys and observable repair checks",{"title":2091,"description":2489},"articles\u002Fprioritize-technical-seo-audit-findings",[2505,2506,2507],"technical SEO","website audits","engineering prioritization","SxuFVuwUn02uVgpIgXT1gMfA5FtNelYWlaTXVThn5iM",{"id":4,"title":5,"author":6,"body":2510,"category":334,"description":335,"extension":336,"featured":337,"heroImage":338,"meta":2708,"navigation":340,"path":341,"publishedAt":342,"readingTime":343,"relatedAgents":2709,"relatedArticles":2710,"relatedWorkflows":2711,"searchIntent":354,"seo":2712,"stem":356,"topics":2713,"updatedAt":361,"visual":362,"__hash__":363},{"type":8,"value":2511,"toc":2701},[2512,2517,2519,2523,2525,2527,2531,2535,2537,2539,2543,2545,2549,2559,2566,2570,2576,2578,2580,2582,2596,2598,2602,2628,2630,2634,2636,2638,2661,2665,2667,2669,2687,2689,2693,2695,2697,2699],[11,2513,13,2514,21],{},[15,2515,20],{"href":17,"rel":2516},[19],[23,2518,26],{"id":25},[11,2520,29,2521,34],{},[31,2522,33],{},[11,2524,37],{},[11,2526,40],{},[42,2528,2529],{},[11,2530,46],{},[11,2532,49,2533,54],{},[15,2534,53],{"href":52},[11,2536,57],{},[23,2538,61],{"id":60},[11,2540,64,2541,69],{},[66,2542,68],{},[11,2544,72],{},[11,2546,2547,78],{},[31,2548,77],{},[11,2550,2551,84,2553,90,2556,96],{},[31,2552,83],{},[15,2554,89],{"href":87,"rel":2555},[19],[15,2557,95],{"href":93,"rel":2558},[19],[11,2560,2561,102,2563,108],{},[31,2562,101],{},[15,2564,107],{"href":105,"rel":2565},[19],[11,2567,2568,114],{},[31,2569,113],{},[11,2571,49,2572,121,2574,126],{},[15,2573,120],{"href":119},[15,2575,125],{"href":124},[23,2577,130],{"id":129},[11,2579,133],{},[11,2581,136],{},[138,2583,2584,2586,2588,2590,2592,2594],{},[141,2585,143],{},[141,2587,146],{},[141,2589,149],{},[141,2591,152],{},[141,2593,155],{},[141,2595,158],{},[11,2597,161],{},[11,2599,164,2600,168],{},[31,2601,167],{},[138,2603,2604,2610,2616,2622],{},[141,2605,2606,176,2608,180],{},[31,2607,175],{},[66,2609,179],{},[141,2611,2612,186,2614,190],{},[31,2613,185],{},[66,2615,189],{},[141,2617,2618,196,2620,200],{},[31,2619,195],{},[66,2621,199],{},[141,2623,2624,206,2626,190],{},[31,2625,205],{},[66,2627,209],{},[11,2629,212],{},[11,2631,49,2632,219],{},[15,2633,218],{"href":217},[23,2635,223],{"id":222},[11,2637,226],{},[228,2639,2640,2647,2654],{},[141,2641,2642,102,2644,239],{},[31,2643,234],{},[15,2645,238],{"href":93,"rel":2646},[19],[141,2648,2649,102,2651,250],{},[31,2650,244],{},[15,2652,249],{"href":247,"rel":2653},[19],[141,2655,2656,102,2658,260],{},[31,2657,255],{},[15,2659,259],{"href":105,"rel":2660},[19],[11,2662,263,2663,268],{},[15,2664,267],{"href":266},[11,2666,271],{},[11,2668,274],{},[138,2670,2671,2675,2679,2683],{},[141,2672,2673,282],{},[31,2674,281],{},[141,2676,2677,288],{},[31,2678,287],{},[141,2680,2681,294],{},[31,2682,293],{},[141,2684,2685,300],{},[31,2686,299],{},[11,2688,303],{},[11,2690,306,2691,311],{},[15,2692,310],{"href":309},[23,2694,315],{"id":314},[11,2696,318],{},[11,2698,321],{},[11,2700,324],{},{"title":326,"searchDepth":327,"depth":327,"links":2702},[2703,2704,2705,2706,2707],{"id":25,"depth":327,"text":26},{"id":60,"depth":327,"text":61},{"id":129,"depth":327,"text":130},{"id":222,"depth":327,"text":223},{"id":314,"depth":327,"text":315},{},[345,346,347],[349,350],[352,353],{"title":5,"description":335},[358,359,360],{"id":2715,"title":2716,"author":6,"body":2717,"category":581,"description":2803,"extension":336,"featured":337,"heroImage":338,"meta":2804,"navigation":340,"path":2805,"publishedAt":2806,"readingTime":2807,"relatedAgents":2808,"relatedArticles":2809,"relatedWorkflows":2812,"searchIntent":2813,"seo":2814,"stem":2815,"topics":2816,"updatedAt":2806,"visual":362,"__hash__":2820},"articles\u002Farticles\u002Fbuilding-ai-finance-department-one-person-business.md","Building an AI finance department for a one-person business",{"type":8,"value":2718,"toc":2797},[2719,2722,2725,2729,2732,2735,2738,2741,2744,2748,2751,2771,2774,2778,2781,2784,2788,2791,2794],[11,2720,2721],{},"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,2723,2724],{},"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.",[23,2726,2728],{"id":2727},"start-with-a-complete-job-not-a-finance-inbox","Start with a complete job, not a finance inbox",[11,2730,2731],{},"Consider a common request: send an agreed invoice, follow up if it remains unpaid, and update the picture once money arrives.",[11,2733,2734],{},"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,2736,2737],{},"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,2739,2740],{},"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,2742,2743],{},"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.",[23,2745,2747],{"id":2746},"the-coordinator-owns-the-case-specialists-can-be-behind-it","The coordinator owns the case; specialists can be behind it",[11,2749,2750],{},"In this setup, one coordinator owns the owner-facing case and calls on narrower help as needed:",[228,2752,2753,2756,2759,2762,2765,2768],{},[141,2754,2755],{},"A receipt task can retain the original document, extract available details, check a likely duplicate, and return the missing business-purpose question.",[141,2757,2758],{},"A bookkeeping task can assemble period inputs and isolate transactions that do not fit the existing information.",[141,2760,2761],{},"An invoice task can prepare or send an invoice only from agreed terms and the authority you gave it.",[141,2763,2764],{},"A collection task can keep payment, invoice, customer context, and follow-up state together.",[141,2766,2767],{},"A cashflow task can refresh a near-term view from known expected receipts and commitments while leaving uncertainty visible.",[141,2769,2770],{},"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,2772,2773],{},"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.",[23,2775,2777],{"id":2776},"decide-what-the-agent-may-finish-without-you","Decide what the agent may finish without you",[11,2779,2780],{},"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,2782,2783],{},"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.",[23,2785,2787],{"id":2786},"give-it-a-real-starting-point-and-a-way-to-continue","Give it a real starting point and a way to continue",[11,2789,2790],{},"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,2792,2793],{},"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,2795,2796],{},"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":326,"searchDepth":327,"depth":327,"links":2798},[2799,2800,2801,2802],{"id":2727,"depth":327,"text":2728},{"id":2746,"depth":327,"text":2747},{"id":2776,"depth":327,"text":2777},{"id":2786,"depth":327,"text":2787},"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","2026-09-06","6 min read",[],[2810,2811],"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":2716,"description":2803},"articles\u002Fbuilding-ai-finance-department-one-person-business",[2817,2818,2819],"AI finance operations","AI agents for solo entrepreneurs","agentic workflows","zQb-2ifRwHwT8i9Z8gTCawiPTMSUzf4ReJ9_4mhXb5w",{"id":2822,"title":2823,"author":6,"body":2824,"category":581,"description":2882,"extension":336,"featured":337,"heroImage":338,"meta":2883,"navigation":340,"path":2884,"publishedAt":2806,"readingTime":2885,"relatedAgents":2886,"relatedArticles":2887,"relatedWorkflows":2890,"searchIntent":2891,"seo":2892,"stem":2893,"topics":2894,"updatedAt":2806,"visual":362,"__hash__":2896},"articles\u002Farticles\u002Fcustomer-paid-invoice-still-open.md","A customer paid. Why is the invoice still open?",{"type":8,"value":2825,"toc":2877},[2826,2829,2832,2836,2839,2842,2846,2849,2852,2855,2858,2862,2865,2868,2871,2874],[11,2827,2828],{},"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,2830,2831],{},"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.",[23,2833,2835],{"id":2834},"give-the-agent-the-facts-and-authority-to-act","Give the agent the facts and authority to act",[11,2837,2838],{},"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,2840,2841],{},"“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.",[23,2843,2845],{"id":2844},"match-the-payment-before-asking-for-the-balance","Match the payment before asking for the balance",[11,2847,2848],{},"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,2850,2851],{},"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,2853,2854],{},"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,2856,2857],{},"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.",[23,2859,2861],{"id":2860},"the-remaining-balance-does-not-settle-the-contact-decision","The remaining balance does not settle the contact decision",[11,2863,2864],{},"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,2866,2867],{},"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,2869,2870],{},"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,2872,2873],{},"After the owner answers, the agent resumes the same item and checks the payment, invoice, and contact state again before acting.",[11,2875,2876],{},"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":326,"searchDepth":327,"depth":327,"links":2878},[2879,2880,2881],{"id":2834,"depth":327,"text":2835},{"id":2844,"depth":327,"text":2845},{"id":2860,"depth":327,"text":2861},"A proposed payment-follow-up agent can match received money, preserve an open balance, and choose the next contact decision for a solo entrepreneur.",{},"\u002Farticles\u002Fcustomer-paid-invoice-still-open","4 min read",[],[2888,2889],"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":2823,"description":2882},"articles\u002Fcustomer-paid-invoice-still-open",[2817,2818,2895],"payment follow-up","PhkJH5CcCG7HgS1o7fPD1h8qH_vJrNA78dYDcwk1bfg",{"id":2898,"title":2899,"author":6,"body":2900,"category":581,"description":3012,"extension":336,"featured":337,"heroImage":338,"meta":3013,"navigation":340,"path":3014,"publishedAt":2806,"readingTime":2807,"relatedAgents":3015,"relatedArticles":3017,"relatedWorkflows":3019,"searchIntent":3022,"seo":3023,"stem":3024,"topics":3025,"updatedAt":2806,"visual":362,"__hash__":3027},"articles\u002Farticles\u002Fmanaging-a-solo-agency-with-ai-agents.md","Managing a solo agency with AI agents",{"type":8,"value":2901,"toc":3005},[2902,2905,2908,2912,2915,2918,2921,2924,2928,2931,2934,2937,2941,2944,2947,2950,2965,2969,2981,2989,2992,2996,2999,3002],[11,2903,2904],{},"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,2906,2907],{},"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.",[23,2909,2911],{"id":2910},"give-the-agency-agent-a-short-business-brief","Give the agency agent a short business brief",[11,2913,2914],{},"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,2916,2917],{},"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,2919,2920],{},"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,2922,2923],{},"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.",[23,2925,2927],{"id":2926},"let-each-engagement-carry-its-own-active-work","Let each engagement carry its own active work",[11,2929,2930],{},"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,2932,2933],{},"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,2935,2936],{},"Later work can start from accepted scope and unresolved questions instead of a generic client thread.",[23,2938,2940],{"id":2939},"coordinate-where-commitments-meet","Coordinate where commitments meet",[11,2942,2943],{},"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,2945,2946],{},"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,2948,2949],{},"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,2951,2952,2953,2958,2959,2964],{},"This resembles a general orchestration pattern where a central agent delegates bounded work, synthesizes returns, and brings judgment back to a person. ",[15,2954,2957],{"href":2955,"rel":2956},"https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents",[19],"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 ",[15,2960,2963],{"href":2961,"rel":2962},"https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Farchitecture\u002Fai-ml\u002Fguide\u002Fai-agent-design-patterns",[19],"Microsoft’s orchestration guidance"," notes. A coordinator should appear when commitments truly cross, not because every business needs a fixed roster.",[23,2966,2968],{"id":2967},"keep-finance-at-the-company-level","Keep finance at the company level",[11,2970,2971,2972,1279,2976,2980],{},"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 ",[15,2973,2975],{"href":2974},"\u002Flibrary\u002Fworkflows\u002Ffinance-receipt-intake\u002F","receipt intake",[15,2977,2979],{"href":2978},"\u002Flibrary\u002Fworkflows\u002Ffinance-payment-request-followups\u002F","payment follow-ups"," belongs here, even when an item relates to a particular project.",[11,2982,2983,2984,2988],{},"A ",[15,2985,2987],{"href":2986},"\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,2990,2991],{},"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.",[23,2993,2995],{"id":2994},"use-the-next-item-to-test-its-placement","Use the next item to test its placement",[11,2997,2998],{},"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,3000,3001],{},"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,3003,3004],{},"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":326,"searchDepth":327,"depth":327,"links":3006},[3007,3008,3009,3010,3011],{"id":2910,"depth":327,"text":2911},{"id":2926,"depth":327,"text":2927},{"id":2939,"depth":327,"text":2940},{"id":2967,"depth":327,"text":2968},{"id":2994,"depth":327,"text":2995},"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",[3016],"stackos-finance-bookkeeping-preparer",[2888,2889,3018],"customer-paid-invoice-still-open",[3020,3021],"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":2899,"description":3012},"articles\u002Fmanaging-a-solo-agency-with-ai-agents",[2818,3026,2819],"agency operations","6Yin2exXGzK2j4Zs6Yz7IF3MFmL4K3kz_oeLbgqPryY",{"id":3029,"title":3030,"author":6,"body":3031,"category":581,"description":3088,"extension":336,"featured":337,"heroImage":338,"meta":3089,"navigation":340,"path":3090,"publishedAt":2806,"readingTime":3091,"relatedAgents":3092,"relatedArticles":3093,"relatedWorkflows":3094,"searchIntent":3095,"seo":3096,"stem":3097,"topics":3098,"updatedAt":2806,"visual":362,"__hash__":3099},"articles\u002Farticles\u002Fwhen-is-a-receipt-actually-processed.md","When is a receipt actually processed?",{"type":8,"value":3032,"toc":3083},[3033,3036,3039,3043,3046,3049,3052,3056,3059,3064,3067,3070,3074,3077,3080],[11,3034,3035],{},"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,3037,3038],{},"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.",[23,3040,3042],{"id":3041},"one-email-can-become-two-separate-receipt-paths","One email can become two separate receipt paths",[11,3044,3045],{},"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,3047,3048],{},"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,3050,3051],{},"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.",[23,3053,3055],{"id":3054},"the-owners-reply-belongs-to-the-item-that-needed-it","The owner’s reply belongs to the item that needed it",[11,3057,3058],{},"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:",[42,3060,3061],{},[11,3062,3063],{},"“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,3065,3066],{},"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,3068,3069],{},"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.",[23,3071,3073],{"id":3072},"the-handoff-is-ready-for-bookkeeping-not-a-bookkeeping-decision","The handoff is ready for bookkeeping, not a bookkeeping decision",[11,3075,3076],{},"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,3078,3079],{},"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,3081,3082],{},"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":326,"searchDepth":327,"depth":327,"links":3084},[3085,3086,3087],{"id":3041,"depth":327,"text":3042},{"id":3054,"depth":327,"text":3055},{"id":3072,"depth":327,"text":3073},"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",[],[2888,2810],[],"Understand how a proposed receipt agent for a solo entrepreneur can prepare receipt evidence without making bookkeeping decisions",{"title":3030,"description":3088},"articles\u002Fwhen-is-a-receipt-actually-processed",[2817,2818,2975],"ss9JQi0_o4oqo9jg3uLFCxSbr_CJ495Ao-XmGd4xNME",{"id":3101,"title":3102,"author":6,"body":3103,"category":581,"description":3269,"extension":336,"featured":337,"heroImage":338,"meta":3270,"navigation":340,"path":3271,"publishedAt":3272,"readingTime":2807,"relatedAgents":3273,"relatedArticles":3276,"relatedWorkflows":3277,"searchIntent":3280,"seo":3281,"stem":3282,"topics":3283,"updatedAt":361,"visual":362,"__hash__":3287},"articles\u002Farticles\u002Fhow-to-separate-issue-investigation-from-implementation.md","How to separate issue investigation from implementation",{"type":8,"value":3104,"toc":3262},[3105,3108,3111,3115,3118,3121,3124,3127,3130,3133,3136,3141,3144,3147,3151,3154,3157,3160,3165,3168,3171,3175,3178,3185,3188,3214,3217,3220,3223,3226,3230,3238,3249,3252,3256,3259],[11,3106,3107],{},"A task titled “Fix CSV export” leaves engineering to guess what should change. Even a convincing diagnosis can leave the scope and the test for success undecided.",[11,3109,3110],{},"Separate issue investigation from implementation by saving what the evidence establishes, identifying the work already authorized, and giving engineering observable acceptance criteria. Carry the unresolved parts into the task so the next agent can check them before choosing a fix.",[23,3112,3114],{"id":3113},"follow-one-report-far-enough-to-know-its-limits","Follow one report far enough to know its limits",[11,3116,3117],{},"Here is a hypothetical software issue. The report, records, and instructions below are invented to show the method.",[11,3119,3120],{},"A user filters a table to show open items, then downloads a CSV. The file includes closed items too. For this example, the agreed behavior is that the export contains every record matching the selected status, across all table pages.",[11,3122,3123],{},"The investigator uses a test fixture with five records: A1, A2, and A3 are open; B1 and B2 are closed. The table shows two records per page. With the Open filter selected, its first page shows A1 and A2, and its second shows A3. The downloaded CSV contains all five records.",[11,3125,3126],{},"That is enough to reproduce a specific mismatch. Keep the fixture, application version, reproduction steps, and resulting CSV together. They give another person or agent a way to repeat the check.",[11,3128,3129],{},"Next, the investigator compares the requests. The table request includes the selected status. The export request omits it. The CSV has the expected columns, and an unfiltered export returns the five expected records.",[11,3131,3132],{},"The missing status is a useful lead. The investigator has not yet traced how the server handles the export request, so the exact cause remains unverified. A change to the client might be sufficient; the server might also ignore a supplied status. Those possibilities affect the implementation.",[11,3134,3135],{},"An investigation conclusion for this case could read:",[42,3137,3138],{},[11,3139,3140],{},"The filtered export failure is reproduced in the named test version. Selecting Open yields a CSV containing A1, A2, A3, B1, and B2; the expected set is A1, A2, and A3. The export request omits the status sent by the table request. The server's handling of that parameter has not been checked. Trace that handling before selecting the correction. Production impact and the version that introduced the issue remain unknown.",[11,3142,3143],{},"Link that conclusion to the fixture, request captures, export, and relevant source references. Keep observations separate from the suspected cause. Correct columns make a column-format defect less relevant to this report; they do not establish that every part of CSV generation works.",[11,3145,3146],{},"If the investigator cannot reproduce the failure, record the conditions tried and the missing evidence. A report that only fails with a particular saved filter may need that filter's configuration next. “Could not reproduce” is a useful result when its limits are clear; it does not establish that the reported issue is resolved.",[23,3148,3150],{"id":3149},"use-the-authorization-you-already-have","Use the authorization you already have",[11,3152,3153],{},"The conclusion helps an operator decide what to do. A likely cause does not itself say whether the agent may create a task, change code, or deploy a result.",[11,3155,3156],{},"Check the current instruction and the project's rules. If they already authorize the necessary work, carry that instruction forward and proceed within its scope. A change of phase is not a reason to ask for the same permission again. If the request only authorized investigation, return the conclusion and recommended next action for the operator's decision.",[11,3158,3159],{},"For the export example, assume the operator has now given this instruction:",[42,3161,3162],{},[11,3163,3164],{},"Create the delivery task and correct status filtering in CSV export. Keep the columns and other export behavior unchanged. Return a reviewed change with checks for filtered and unfiltered exports. Do not deploy it.",[11,3166,3167],{},"This gives engineering room to trace the server behavior and choose the correction. It does not commit the team to the investigator's first suspected code path. If that path turns out to be wrong, update the explanation and supporting evidence while pursuing the authorized behavior.",[11,3169,3170],{},"A broader change needs its own scope decision. Replacing the reporting system would go beyond this instruction. So would silently changing the export to include only the current table page.",[23,3172,3174],{"id":3173},"give-engineering-a-behavior-it-can-test","Give engineering a behavior it can test",[11,3176,3177],{},"The delivery task should carry the investigation conclusion, its evidence links, the applicable instruction, the affected export path, and the remaining uncertainty. Add any dependencies and a named owner for the work. Engineering should be able to retrieve the original report without searching a chat history for it.",[11,3179,3180,3181,3184],{},"For this case, write the desired behavior explicitly: ",[31,3182,3183],{},"CSV export uses the selected status and includes matching records from every page."," Keep the current columns and their order. The task can require checking the server's handling of the status before deciding where to change the code.",[11,3186,3187],{},"Use the same fixture to make acceptance concrete:",[228,3189,3190,3196,3202,3208],{},[141,3191,3192,3195],{},[31,3193,3194],{},"Open is selected while the first table page is visible:"," export A1, A2 and A3, including the record on the second page.",[141,3197,3198,3201],{},[31,3199,3200],{},"Closed is selected:"," export B1 and B2.",[141,3203,3204,3207],{},[31,3205,3206],{},"No status filter is selected:"," export all five records.",[141,3209,3210,3213],{},[31,3211,3212],{},"A status with no matching records is selected:"," export the agreed CSV headers with no data rows.",[11,3215,3216],{},"In this example, a header-only file is the chosen behavior for an empty result. A real project should use its existing export contract or settle that question before treating it as a test expectation.",[11,3218,3219],{},"Compare record identifiers as well as counts. A three-row export can still contain the wrong three records. Check the column names and order alongside the records so a filtering fix does not quietly change the file format.",[11,3221,3222],{},"The verification plan should also name where the checks will run and what will be saved. Here, engineering can reproduce the failure against the original version in a local test environment, add a regression check that exposes it, then run that check against the changed version. Exercise the export through its normal entry point so the result covers the request and server behavior together. Retain the fixture, version identifiers, command or test procedure, results, and sample CSVs.",[11,3224,3225],{},"Those checks cover the stated export behavior. They do not answer the investigation's separate question about which production users were affected. Keep that question visible if someone still needs to investigate it.",[23,3227,3229],{"id":3228},"how-stackos-separates-these-responsibilities","How StackOS separates these responsibilities",[11,3231,3232,3233,3237],{},"StackOS's ",[15,3234,3236],{"href":3235},"\u002Flibrary\u002Fworkflows\u002Fsupport-issue-investigation\u002F","Issue Investigation workflow"," instructs the agent to read the full support thread, distinguish facts from inferences and eliminated hypotheses, and return a conclusion with evidence and remaining uncertainty. It allows a verified cause, bounded uncertainty with a next diagnostic, or no issue. Its assignment ends with the conclusion; creating delivery tasks and implementing production fixes belong to later work.",[11,3239,49,3240,3244,3245,190],{},[15,3241,3243],{"href":3242},"\u002Flibrary\u002Fworkflows\u002Fsupport-delivery-task-handoff\u002F","Delivery Task Handoff workflow"," checks for a completed conclusion and a current operator instruction in the same support thread. It carries the evidence, scope, acceptance criteria, verification expectations, and residual risk into tracker work, then hands implementation to ",[15,3246,3248],{"href":3247},"\u002Flibrary\u002Fworkflows\u002Fengineering-tracked-delivery\u002F","engineering delivery",[11,3250,3251],{},"The same-thread requirement belongs to this support method. It tells the handoff agent where to establish the instruction for that issue. The agent still has to interpret the instruction and judge what the evidence supports; a saved reference alone cannot make a diagnosis correct.",[23,3253,3255],{"id":3254},"review-the-fix-against-the-report","Review the fix against the report",[11,3257,3258],{},"Before accepting the export change, open the original report, the authorized scope, and the verification results together. Confirm that the test actually failed for the reported reason on the original version, then check the output produced by the changed version. Review the neighboring cases as well as the Open filter that first exposed the problem.",[11,3260,3261],{},"A note saying “all tests pass” leaves the reviewer to reconstruct that connection. A record showing the original five-row export, the corrected A1\u002FA2\u002FA3 export, and the unchanged columns makes the result inspectable. It gives the reviewer enough evidence to accept the correction against the behavior the operator asked for.",{"title":326,"searchDepth":327,"depth":327,"links":3263},[3264,3265,3266,3267,3268],{"id":3113,"depth":327,"text":3114},{"id":3149,"depth":327,"text":3150},{"id":3173,"depth":327,"text":3174},{"id":3228,"depth":327,"text":3229},{"id":3254,"depth":327,"text":3255},"Turn a software issue report into a supported conclusion, an authorized change, and acceptance checks. Follow a worked CSV export example.",{},"\u002Farticles\u002Fhow-to-separate-issue-investigation-from-implementation","2026-07-28",[3274,3275],"support-workflow-issue-investigator","support-workflow-delivery-handoff",[1836,2497,589],[3278,3279,2500],"support-issue-investigation","support-delivery-task-handoff","Learn how to separate issue investigation, operator authorization, and engineering implementation so a plausible diagnosis does not silently become a fix plan",{"title":3102,"description":3269},"articles\u002Fhow-to-separate-issue-investigation-from-implementation",[3284,3248,3285,3286,1844],"issue investigation","operator authorization","support operations","FVkZgHTi_JoA5ogAnYOG-wo90PcURmThj_QVr-x4LtM",{"id":3289,"title":3290,"author":6,"body":3291,"category":581,"description":3344,"extension":336,"featured":337,"heroImage":338,"meta":3345,"navigation":340,"path":3346,"publishedAt":3347,"readingTime":3091,"relatedAgents":3348,"relatedArticles":3350,"relatedWorkflows":3351,"searchIntent":3352,"seo":3353,"stem":3354,"topics":3355,"updatedAt":179,"visual":362,"__hash__":3360},"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":3292,"toc":3340},[3293,3296,3299,3304,3308,3311,3320,3324,3327,3330,3333],[11,3294,3295],{},"Receiving a blocker message does not make you responsible for the repair. It should tell you which action is waiting, why, and what help the agent actually needs.",[11,3297,3298],{},"If the agent already has the authority and context to recover, it should use that permitted path and continue. When it needs someone else's action or a decision about authority, a proposed message could read:",[42,3300,3301],{},[11,3302,3303],{},"I can't save the evidence record yet: the required write permission is unavailable. If you're authorized to start the research step, please start it. If you aren't authorized, use the established route for this request if one exists. If no route is known, let me know that ownership is still unresolved. I'll check the active step and write permission before attempting to save the record.",[23,3305,3307],{"id":3306},"make-the-request-conditional-on-authority","Make the request conditional on authority",[11,3309,3310],{},"If the recipient cannot act, an established route may lead to someone who can. Where no such route is known, leave the ownership question open. Asking the recipient to identify that gap is more precise than assigning them a repair they may have no way to perform.",[11,3312,3313,3314,3319],{},"GOV.UK separates these cases in its ",[15,3315,3318],{"href":3316,"rel":3317},"https:\u002F\u002Fdesign-system.service.gov.uk\u002Fcomponents\u002Ferror-message\u002F",[19],"error-message guidance",". Validation messages should explain a problem the user can correct. Permission or service problems the user cannot fix need an explanation and useful information about what happens next. This is service-design guidance; applying the distinction here means checking what the recipient can actually do before asking them to do it.",[23,3321,3323],{"id":3322},"check-the-state-before-continuing","Check the state before continuing",[11,3325,3326],{},"In a July 2026 StackOS run, a toolbox inspection showed the evidence-write operation unavailable before the research step was claimed. After the claim, another inspection listed the operation as granted. The receipt records that change in tool availability. It does not show a write attempt or a saved-record result, and it identifies no repair owner.",[11,3328,3329],{},"That observation gives the proposed message a concrete restart check. A reply saying someone can claim the step is an ownership signal. The agent still needs to inspect which step is active and whether the required write operation is available.",[11,3331,3332],{},"For an agent continuing this task, the procedure would be to verify those conditions, attempt the authorized write, then inspect the returned result and retrieve the record to check its contents before reporting it saved. Each check answers the next practical question: can the operation run, did it return success, and does the saved record contain the intended evidence?",[11,3334,3335,3336,3339],{},"If another agent takes over, include the waiting action and its unmet condition in the ",[15,3337,3338],{"href":1817},"handoff",". If permission or ownership remains unresolved, leave the evidence write waiting with the specific condition still needed to continue.",{"title":326,"searchDepth":327,"depth":327,"links":3341},[3342,3343],{"id":3306,"depth":327,"text":3307},{"id":3322,"depth":327,"text":3323},"Use a short blocker message to explain the waiting action, ask for help within the recipient's authority, and show what the agent must check before continuing.",{},"\u002Farticles\u002Fhow-ai-agents-should-explain-blockers-to-humans","2026-07-27",[347,587,3349],"branding-sanitization-reviewer",[2497,2810,1836],[353,2500],"See how an AI agent can explain one recoverable blocker without assuming who owns the repair",{"title":3290,"description":3344},"articles\u002Fhow-ai-agents-should-explain-blockers-to-humans",[3356,3357,3358,3359],"AI agent blockers","human-AI interaction","workflow recovery","agent authority","i9YIPO51A8zewbmcKh4YpWkrKb71cYnhQdIwtIkv7Ho",{"id":3362,"title":3363,"author":6,"body":3364,"category":581,"description":3536,"extension":336,"featured":337,"heroImage":338,"meta":3537,"navigation":340,"path":3538,"publishedAt":3347,"readingTime":2807,"relatedAgents":3539,"relatedArticles":3540,"relatedWorkflows":3541,"searchIntent":3542,"seo":3543,"stem":3544,"topics":3545,"updatedAt":361,"visual":3549,"__hash__":3550},"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":3365,"toc":3529},[3366,3369,3372,3375,3378,3382,3385,3388,3393,3396,3399,3404,3407,3411,3414,3417,3422,3425,3428,3431,3434,3439,3442,3445,3450,3453,3456,3460,3463,3470,3473,3476,3479,3483,3486,3489,3494,3497,3502,3505,3508,3512,3515,3518,3521,3524],[11,3367,3368],{},"In a July 2026 StackOS article review, the agents marked the draft ready. The operator read it and found problems with its voice and structure, even though the agents had current writing guidance.",[11,3370,3371],{},"The review labels left an editorial decision unresolved: what needed to change in this particular draft?",[11,3373,3374],{},"A claim review can establish support for the sentences it checks. The article still needs to give its reader something useful to understand or decide. When that is missing, asking the writer to “sound more human” leaves it to guess what went wrong.",[11,3376,3377],{},"Start with a passage. Explain what it leaves unresolved, then trace the problem to the source material, brief, structure, or wording. The July occurrence gives us a reason to make that distinction; it does not tell us that a revised process solved the problem.",[23,3379,3381],{"id":3380},"make-the-complaint-specific","Make the complaint specific",[11,3383,3384],{},"“This sounds generic” can mean several things. The paragraph may make a claim without explaining what happened. It may offer advice to an undefined reader. Or the article may repeat a point another page already covers.",[11,3386,3387],{},"Here is an invented passage:",[42,3389,3390],{},[11,3391,3392],{},"Teams should establish effective review processes to ensure that AI-generated content meets their quality standards.",[11,3394,3395],{},"You can replace “establish” with “set up” and make the sentence easier to read. The editor still has no decision to make. Which review? What should it inspect? What finding would require the draft to change?",[11,3397,3398],{},"A useful comment would identify that omission:",[42,3400,3401],{},[11,3402,3403],{},"This paragraph recommends review but never explains what the reviewer should look for. Give the editor a concrete finding and show which decision it would reopen.",[11,3405,3406],{},"That gives the writer something to work on. It also gives you a way to check the revision: does the new passage explain an editorial decision, or does it still recommend being careful in different words?",[23,3408,3410],{"id":3409},"check-what-the-writer-had-to-work-with","Check what the writer had to work with",[11,3412,3413],{},"The next examples are also hypothetical. They show two problems that can produce vague writing but need different repairs.",[11,3415,3416],{},"Suppose a draft says:",[42,3418,3419],{},[11,3420,3421],{},"The new review process made our content more useful.",[11,3423,3424],{},"The supplied notes say that reviewers completed their checks. They contain no example of a changed article or a reader using it.",[11,3426,3427],{},"The writer lacks support for the improvement claim. Ask for the missing account: what did someone notice, what changed, and what evidence supports the claimed difference? An attributable description of an editorial decision may be enough for a modest account of that decision. A measured improvement needs evidence of the improvement.",[11,3429,3430],{},"If the source cannot supply it, narrow or remove the claim. A more vivid sentence would still leave the same gap. Do not let the writer invent an incident to make the article feel specific.",[11,3432,3433],{},"Now suppose the sources are useful, but the brief says only:",[42,3435,3436],{},[11,3437,3438],{},"Write an article about AI content review.",[11,3440,3441],{},"That names a topic. It leaves the writer to choose the reader, the problem, and how much ground to cover. A survey of research, drafting, review, publishing, and measurement would all fit.",[11,3443,3444],{},"For a narrower article, the brief could say:",[42,3446,3447],{},[11,3448,3449],{},"Help an editor decide what to reopen when an AI-assisted draft has passed its checks but still gives the reader little to use. Show how to distinguish missing evidence, an unclear point, and wording that obscures an otherwise useful explanation.",[11,3451,3452],{},"The revised brief changes what belongs in the article. A paragraph describing every role in a content team now needs a reason to stay. A concrete example of an unusable review comment has a clear job.",[11,3454,3455],{},"Make that choice before asking for another draft. Otherwise, the writer has to infer the point again while rewriting the prose.",[23,3457,3459],{"id":3458},"read-it-beside-the-nearest-existing-article","Read it beside the nearest existing article",[11,3461,3462],{},"An article can have sound evidence and a clear brief, then drift as it develops. Read the whole draft beside the closest piece you already publish.",[11,3464,3465,3466,3469],{},"For this article, ",[15,3467,3468],{"href":410},"How to build an AI agent workflow"," already explains goals, step contracts, state, and orchestration. Repeating that explanation here would spend the reader's attention on workflow design before helping them diagnose a paragraph.",[11,3471,3472],{},"Compare what each section lets the reader understand or do. If a section disappeared, which necessary part of the argument would disappear with it? If the answer is already supplied by the neighboring guide, a short explanation and link may be enough.",[11,3474,3475],{},"Look at the form too. An existing article can demonstrate useful directness without supplying the next article's opening, section sequence, and ending. Compare the actual prose with the approved voice examples: who acts, what happens, why the consequence matters, and how the explanation develops. Borrowing the outline can conceal that those parts are still missing.",[11,3477,3478],{},"This is a judgment about the piece in front of you. A familiar heading or sentence pattern is not, by itself, a defect.",[23,3480,3482],{"id":3481},"leave-room-for-a-sentence-edit","Leave room for a sentence edit",[11,3484,3485],{},"Sometimes the evidence and argument already work. The wording is simply making the reader work too hard.",[11,3487,3488],{},"Consider this invented instruction:",[42,3490,3491],{},[11,3492,3493],{},"An assessment of the degree of correspondence between the introductory framing and the subsequent development should be undertaken.",[11,3495,3496],{},"You can say:",[42,3498,3499],{},[11,3500,3501],{},"Read the opening beside the rest of the article. Mark any promise the body does not fulfill.",[11,3503,3504],{},"The second version names the action and tells the editor what to notice. It does not need another research pass or a new angle.",[11,3506,3507],{},"Use the smallest repair that addresses the actual problem. Reopening a settled brief for every awkward sentence gives the writer new decisions to make without explaining what was wrong with the old ones.",[23,3509,3511],{"id":3510},"return-a-repair-the-writer-can-use","Return a repair the writer can use",[11,3513,3514],{},"The coordinating editor needs the draft, the brief, the relevant sources, and the review findings together. Specialist verdicts help with that decision; each covers the responsibility assigned to its reviewer.",[11,3516,3517],{},"For a material finding, name the passage, its effect on the reader, the source or instruction it conflicts with, and the change you need. The writer should also know what is already sound and should remain intact.",[11,3519,3520],{},"After the repair, read the changed passage in place. A sharper opening can create a promise the later sections still fail to fulfill. Check that connection before accepting the article, and check that the revision has not introduced unsupported detail.",[11,3522,3523],{},"For the hypothetical review article above, a repair request could be this specific:",[42,3525,3526],{},[11,3527,3528],{},"The opening promises help diagnosing a weak draft, but the next section only lists content-workflow roles. Replace that section with one example of a passage the editor would send back. Explain what it fails to tell the reader and whether the writer needs better source material, a clearer brief, or a sentence edit. Keep the existing claim boundaries. Return the revised section with the brief and sources you used so I can read it in context.",{"title":326,"searchDepth":327,"depth":327,"links":3530},[3531,3532,3533,3534,3535],{"id":3380,"depth":327,"text":3381},{"id":3409,"depth":327,"text":3410},{"id":3458,"depth":327,"text":3459},{"id":3481,"depth":327,"text":3482},{"id":3510,"depth":327,"text":3511},"Find why an AI-written draft feels generic. Use concrete examples to trace the problem to missing evidence, a vague brief, repeated structure, or wording.",{},"\u002Farticles\u002Fhow-to-build-ai-content-workflow-that-does-not-sound-generic",[345,347,587,848,3349],[589,2497,1836],[353],"Diagnose why an AI content workflow can still produce generic-seeming prose and decide which editorial decision to reopen",{"title":3363,"description":3536},"articles\u002Fhow-to-build-ai-content-workflow-that-does-not-sound-generic",[3546,858,3547,857,3548],"AI content workflow","editorial operations","content review","roles","jcHg3Bf6ugbzGrvNXtYphgWWFK0nSUg8JAlgdpgeWaU",{"id":3552,"title":3553,"author":6,"body":3554,"category":581,"description":3720,"extension":336,"featured":337,"heroImage":338,"meta":3721,"navigation":340,"path":3722,"publishedAt":3347,"readingTime":343,"relatedAgents":3723,"relatedArticles":3724,"relatedWorkflows":3726,"searchIntent":3727,"seo":3728,"stem":3729,"topics":3730,"updatedAt":3347,"visual":362,"__hash__":3734},"articles\u002Farticles\u002Fhow-to-do-keyword-research-for-ai-search.md","How to do keyword research for AI search",{"type":8,"value":3555,"toc":3715},[3556,3563,3566,3582,3595,3608,3621,3625,3628,3641,3649,3658,3662,3665,3668,3671,3674,3678],[11,3557,3558,3559,3562],{},"The query “how to do keyword research for AI search” returned ",[66,3560,3561],{},"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,3564,3565],{},"The July case was kept as a small ledger instead of compressed into a single volume judgment.",[428,3567,3572,3577],{"decision-label":3568,"evidence-label":3569,"label":3570,"record-heading":3571},"Use in the decision","What the July case established","Question origin","Record",[435,3573,3574],{"v-slot:evidence":326},[11,3575,3576],{},"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.",[435,3578,3579],{"v-slot:decision":326},[11,3580,3581],{},"The query belonged to a documented problem-first research corpus.",[428,3583,3585,3590],{"decision-label":3568,"evidence-label":3569,"label":3584,"record-heading":3571},"Measurement receipt",[435,3586,3587],{"v-slot:evidence":326},[11,3588,3589],{},"A 472-phrase request hit a phrase-length limit; a corrected 448-phrase request completed after 24 over-limit questions were excluded.",[435,3591,3592],{"v-slot:decision":326},[11,3593,3594],{},"Provider task status and endpoint limits became part of the interpretation.",[428,3596,3598,3603],{"decision-label":3568,"evidence-label":3569,"label":3597,"record-heading":3571},"Result snapshots",[435,3599,3600],{"v-slot:evidence":326},[11,3601,3602],{},"Eight selected US\u002Fen snapshots from July 12 each contained an AI Overview; the primary query was outside that sample.",[435,3604,3605],{"v-slot:decision":326},[11,3606,3607],{},"The snapshots described related observations from that date.",[428,3609,3611,3616],{"decision-label":3568,"evidence-label":3569,"label":3610,"record-heading":3571},"Evidence and ownership",[435,3612,3613],{"v-slot:evidence":326},[11,3614,3615],{},"The research ledger preserved the method and the July 25 article corpus was reviewed.",[435,3617,3618],{"v-slot:decision":326},[11,3619,3620],{},"The question could be assessed as a separate reader job with a named evidence record.",[23,3622,3624],{"id":3623},"what-the-measurement-instrument-actually-returned","What the measurement instrument actually returned",[11,3626,3627],{},"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,3629,3630,3631,3636,3637,3640],{},"The selected ",[15,3632,3635],{"href":3633,"rel":3634},"https:\u002F\u002Fdocs.dataforseo.com\u002Fv3\u002Fkeywords_data-google_ads-search_volume-live\u002F",[19],"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 ",[66,3638,3639],{},"search_volume"," field. The primary query also had null CPC and paid-competition fields.",[11,3642,3643,3648],{},[15,3644,3647],{"href":3645,"rel":3646},"https:\u002F\u002Fsupport.google.com\u002Fgoogle-ads\u002Fanswer\u002F3022575?hl=en",[19],"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,3650,3651,3652,3657],{},"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 ",[15,3653,3656],{"href":3654,"rel":3655},"https:\u002F\u002Fdevelopers.google.com\u002Fsearch\u002Fdocs\u002Fappearance\u002Fai-features",[19],"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.",[23,3659,3661],{"id":3660},"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,3663,3664],{},"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,3666,3667],{},"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,3669,3670],{},"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,3672,3673],{},"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.",[23,3675,3677],{"id":3676},"disposition-for-this-candidate","Disposition for this candidate",[928,3679,3680,3689],{},[931,3681,3682],{},[934,3683,3684,3687],{},[937,3685,3686],{},"Status",[937,3688,3571],{},[947,3690,3691,3699,3707],{},[934,3692,3693,3696],{},[952,3694,3695],{},"Proceed",[952,3697,3698],{},"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.",[934,3700,3701,3704],{},[952,3702,3703],{},"Hold",[952,3705,3706],{},"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.",[934,3708,3709,3712],{},[952,3710,3711],{},"Reject",[952,3713,3714],{},"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":326,"searchDepth":327,"depth":327,"links":3716},[3717,3718,3719],{"id":3623,"depth":327,"text":3624},{"id":3660,"depth":327,"text":3661},{"id":3676,"depth":327,"text":3677},"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",[2077,346,345,347],[349,3725,589],"how-to-use-product-evidence-without-writing-a-product-pitch",[352,353],"Learn how to research natural-language questions for AI search using problem evidence, conventional keyword data, result inspection, and accountable source records",{"title":3553,"description":3720},"articles\u002Fhow-to-do-keyword-research-for-ai-search",[3731,3732,360,3733],"keyword research","AI search","editorial evidence","6l9G_5OfAmmabHA1boNRvktNFLGK69R0xRWh8c2a_yM",{"id":3736,"title":3737,"author":6,"body":3738,"category":581,"description":3834,"extension":336,"featured":337,"heroImage":338,"meta":3835,"navigation":340,"path":3836,"publishedAt":3347,"readingTime":2885,"relatedAgents":3837,"relatedArticles":3838,"relatedWorkflows":3840,"searchIntent":3841,"seo":3842,"stem":3843,"topics":3844,"updatedAt":3849,"visual":362,"__hash__":3850},"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":3739,"toc":3829},[3740,3743,3746,3749,3753,3756,3759,3762,3765,3768,3773,3776,3780,3783,3788,3791,3794,3797,3804,3807,3813,3817,3820,3823,3826],[11,3741,3742],{},"Before turning a test report into an article, decide what a reader could do with it.",[11,3744,3745],{},"An operator evaluating a product claim may need to know how much of the implementation was checked and what they would still need to verify. That gives you a reason to explain the tests, the behavior they covered, and the environment they ran in. A tour of the feature's other capabilities would answer a different question.",[11,3747,3748],{},"The product supplies the case. Your job as the author is to explain the decision it makes possible.",[23,3750,3752],{"id":3751},"what-the-connection-flow-tests-established","What the connection-flow tests established",[11,3754,3755],{},"A StackOS delivery on July 22, 2026 provides a useful example. Focused tests exposed missing behavior in an interactive account connection flow: setup lacked a single Connect action, application settings were not saved before authorization began, and the returned authorization state was not displayed and cleared.",[11,3757,3758],{},"Later checks against the project code covered the implemented path. It presented one Connect action, validated and stored the required application fields, started authorization, handled the result on return, and cleared the returned state after reading it.",[11,3760,3761],{},"The live in-app click-through was not performed in that delivery because the required browser backend was unavailable. That matters to the article: the records covered the implementation in repository checks, while the live interaction remained untested. They describe that July delivery, not the state of a current release.",[11,3763,3764],{},"A sentence such as “the connection experience is seamless” would go well beyond those records. It would give the reader a judgment about the experience without a corresponding observation of someone using it.",[11,3766,3767],{},"A supported account could read:",[42,3769,3770],{},[11,3771,3772],{},"In the July 22 delivery, repository checks covered the implemented Connect action, setup persistence, and handling of the authorization result. The live in-app click-through was not performed.",[11,3774,3775],{},"Now an operator can distinguish an implementation claim from a claim about the complete live journey. If their decision depends on that journey, they know which evidence is still needed. They can ask the same question of another product's test report: which behavior was checked, and in which environment?",[23,3777,3779],{"id":3778},"choose-details-around-that-decision","Choose details around that decision",[11,3781,3782],{},"Before expanding the case, complete a working sentence:",[42,3784,3785],{},[11,3786,3787],{},"After reading, the reader should be able to ______ because this example shows ______.",[11,3789,3790],{},"For this piece, the decision is whether the evidence is enough to rely on an implementation claim.",[11,3792,3793],{},"Use that purpose to decide what stays. The missing behavior explains what the work set out to change. The test environment determines how far the resulting claim can go. A description of unrelated account-management features would add product information without helping the reader make this judgment.",[11,3795,3796],{},"This also gives you a way to choose between possible examples. Prefer the one that lets you explain the reader's decision with concrete evidence. A larger release or more impressive feature may be less useful if its records do not show the distinction the article needs.",[11,3798,3799,3803],{},[15,3800,3802],{"href":17,"rel":3801},[19],"Google's people-first content guidance"," asks whether content adds original information or analysis, serves an intended audience, and helps readers achieve their goal. Those are useful questions when choosing a case. They do not establish how an article will rank.",[11,3805,3806],{},"Then try the original paragraph with the product name temporarily removed. The explanation of what was checked and why that matters should still make sense. The company name should not have to do the argumentative work.",[11,3808,3809,3810,190],{},"Keep the name in the finished piece when it makes the case attributable. This scratch check helps you see whether you have explained a useful idea or merely described something you built. When the point remains unclear, ",[15,3811,3812],{"href":787},"revisit the article's reader task and brief",[23,3814,3816],{"id":3815},"when-the-evidence-supports-a-different-piece","When the evidence supports a different piece",[11,3818,3819],{},"Sometimes the article you want depends on an observation you do not have. A story about easier onboarding needs support for the experience it describes. A story about customer response needs an account of that response. Passing implementation checks cannot fill either gap.",[11,3821,3822],{},"You can collect the missing evidence or choose a narrower point. The July case still supports an article about judging verification scope because the unperformed live test is part of that explanation. It would not support a success story about the complete connection experience.",[11,3824,3825],{},"There is also room for a straightforward release note. If the useful news is that a feature was added or changed, describe that change and its verified scope in the appropriate format. It does not need to become a broader lesson.",[11,3827,3828],{},"If the proposed article only works after you leave out the fact that changes the reader's decision, either change the premise or wait for the missing evidence.",{"title":326,"searchDepth":327,"depth":327,"links":3830},[3831,3832,3833],{"id":3751,"depth":327,"text":3752},{"id":3778,"depth":327,"text":3779},{"id":3815,"depth":327,"text":3816},"Choose product details that help a reader judge a claim. Work through a real connection-flow example, its test scope, and the decision it supports.",{},"\u002Farticles\u002Fhow-to-use-product-evidence-without-writing-a-product-pitch",[346,345,347,587,848,3349],[349,589,3839],"how-ai-agents-use-accounts-safely",[353],"Decide how to use bounded product evidence in an article without turning the product itself into the thesis",{"title":3737,"description":3834},"articles\u002Fhow-to-use-product-evidence-without-writing-a-product-pitch",[3845,3846,3547,3847,3848],"product evidence","content substantiation","AI content fact checking","reader-first content","2026-10-01","-P7kzUkBpgxoWu7nJXmvv4atMOMsmi-0lcCsNx5e5G8",{"id":3852,"title":3853,"author":6,"body":3854,"category":843,"description":4056,"extension":336,"featured":337,"heroImage":338,"meta":4057,"navigation":340,"path":4058,"publishedAt":4059,"readingTime":585,"relatedAgents":4060,"relatedArticles":4061,"relatedWorkflows":4063,"searchIntent":4064,"seo":4065,"stem":4066,"topics":4067,"updatedAt":3849,"visual":362,"__hash__":4069},"articles\u002Farticles\u002Fhow-to-fact-check-ai-generated-content.md","Fact-check AI-generated content one claim at a time",{"type":8,"value":3855,"toc":4049},[3856,3859,3862,3866,3869,3874,3877,3882,3885,3888,3891,3896,3899,3902,3906,3924,3927,3959,3962,3965,3974,3978,3981,4007,4010,4013,4017,4020,4028,4036,4039,4043,4046],[11,3857,3858],{},"A real source can sit beside a sentence it does not support. The link works, the report discusses the right subject, and a few words in the draft still go beyond what anyone established.",[11,3860,3861],{},"To fact-check AI-generated content, take each material claim back to the passage that is supposed to support it. Compare the exact wording, scope, and date before deciding whether the sentence can stay.",[23,3863,3865],{"id":3864},"follow-the-claim-into-the-source","Follow the claim into the source",[11,3867,3868],{},"Consider this hypothetical draft sentence:",[42,3870,3871],{},[11,3872,3873],{},"AI summaries cut support response times.",[11,3875,3876],{},"The draft cites a pilot report. For this example, the report and its findings are also invented. Its relevant passage says:",[42,3878,3879],{},[11,3880,3881],{},"During a two-week pilot, one support team's median time to first reply was lower than in the previous two weeks. The team introduced AI summaries and a new triage queue together. The pilot did not separate their effects.",[11,3883,3884],{},"The report supports an observation about one team over a particular period. The draft makes a causal claim about AI summaries.",[11,3886,3887],{},"Open the report and read the surrounding explanation. In this example, the change to the triage queue matters: the report does not tell us which intervention affected reply times. Nor does one team's pilot establish what happens across support teams generally. Even the metric needs care. “Time to first reply” describes something more specific than an undefined “response time.”",[11,3889,3890],{},"A supported rewrite would be:",[42,3892,3893],{},[11,3894,3895],{},"In one support team's two-week pilot, median time to first reply was lower than in the previous two weeks. The team introduced AI summaries and a new triage queue together; the pilot did not establish their separate effects.",[11,3897,3898],{},"That wording keeps the observation and the information needed to interpret it. If the article needs to establish that AI summaries caused the improvement, this source cannot finish the job.",[11,3900,3901],{},"Adding “may have” to the original sentence would leave the causal explanation unresolved. Decide whether the article needs that explanation, then find evidence suited to it or remove it. Do not use a softer verb to hide the missing check.",[23,3903,3905],{"id":3904},"ask-five-questions-of-each-material-claim","Ask five questions of each material claim",[11,3907,3908,3909,807,3913,807,3916,3919,3920,3923],{},"A sentence can contain several propositions. Words such as ",[3910,3911,3912],"em",{},"stores",[3910,3914,3915],{},"exposes",[3910,3917,3918],{},"prevents",", and ",[3910,3921,3922],{},"guarantees"," each assert behavior that may need different evidence. Split the sentence when that makes the review clearer.",[11,3925,3926],{},"For each claim, ask:",[138,3928,3929,3935,3941,3947,3953],{},[141,3930,3931,3934],{},[31,3932,3933],{},"What does the sentence literally say?"," Include the implications of words such as “all,” “always,” “only,” and “because.”",[141,3936,3937,3940],{},[31,3938,3939],{},"Does the source cover that system, population, version, and period?"," A finding about one pilot or an older release has a narrower reach than a general present-tense claim.",[141,3942,3943,3946],{},[31,3944,3945],{},"Is the source reporting a fact, an interpretation, or a recommendation?"," Advice to adopt a practice does not establish that someone adopted it or that it worked.",[141,3948,3949,3952],{},[31,3950,3951],{},"Does the wording claim causation where the evidence shows only association or sequence?"," In the example, faster replies followed two simultaneous changes.",[141,3954,3955,3958],{},[31,3956,3957],{},"Which uncertainty has to remain attached to the sentence?"," Keep the limits a reader needs to understand the finding, especially when removing them would change the conclusion.",[11,3960,3961],{},"Numbers, dates, definitions, product capabilities, policy requirements, safety claims, and causal explanations deserve this attention. A transition usually needs less. Match the depth of review to the consequence of being wrong.",[11,3963,3964],{},"Keep a small record beside the draft: the exact claim, source and relevant passage, source date or version, what supports or contradicts the wording, and the editorial decision. A URL alone leaves the next reviewer to find the passage and infer why you accepted it.",[11,3966,3967,3968,3973],{},"NIST's ",[15,3969,3972],{"href":3970,"rel":3971},"https:\u002F\u002Fnvlpubs.nist.gov\u002Fnistpubs\u002Fai\u002FNIST.AI.600-1.pdf",[19],"Generative AI Profile"," recommends documenting fact-checking and reviewing sources and citations as part of managing generative AI risks. That supports keeping an inspectable record; it does not establish that a particular checklist eliminates errors.",[23,3975,3977],{"id":3976},"give-the-claim-a-decision","Give the claim a decision",[11,3979,3980],{},"After comparing the sentence with its evidence, choose what happens to it:",[228,3982,3983,3989,3995,4001],{},[141,3984,3985,3988],{},[31,3986,3987],{},"Keep it."," The source supports the wording, scope, and date.",[141,3990,3991,3994],{},[31,3992,3993],{},"Qualify it."," A narrower statement is supported. In the hypothetical pilot, keep the observed change and the limits on attributing its cause.",[141,3996,3997,4000],{},[31,3998,3999],{},"Remove it."," Support is absent or contradictory, and the article does not need to pursue the claim further.",[141,4002,4003,4006],{},[31,4004,4005],{},"Escalate it."," The claim matters, but a stronger source or someone with relevant expertise must resolve it.",[11,4008,4009],{},"Write the repair where possible. “Overstated” tells the author less than identifying the unsupported cause and supplying the narrower observation.",[11,4011,4012],{},"For medical, legal, financial, security, and other consequential subjects, the decision may need a qualified domain reviewer. Preserve the question they must resolve. A general editor can identify missing support without being qualified to decide the underlying issue.",[23,4014,4016],{"id":4015},"check-provenance-and-disclosure-for-their-own-purposes","Check provenance and disclosure for their own purposes",[11,4018,4019],{},"Factual review asks whether evidence supports a claim. Provenance asks what is known about the content's origin and history. Disclosure asks what readers should be told about its author, production, or purpose.",[11,4021,4022,4027],{},[15,4023,4026],{"href":4024,"rel":4025},"https:\u002F\u002Fspec.c2pa.org\u002Fspecifications\u002Fspecifications\u002F2.2\u002Fexplainer\u002FExplainer.html",[19],"C2PA's explainer"," describes Content Credentials as evidence about origin, history, and integrity. That information alone cannot establish that the content is factually accurate. Missing credentials do not, by themselves, establish that it is false either.",[11,4029,4030,4031,4035],{},"Google's ",[15,4032,4034],{"href":17,"rel":4033},[19],"people-first content guidance"," encourages clear authorship and useful explanations of how content was produced, including automation disclosures when readers would reasonably expect them.",[11,4037,4038],{},"Those checks can matter for the same article. Neither an authorship label nor a detector score settles whether the pilot report supports the draft's causal claim. The sentence still needs its source comparison.",[23,4040,4042],{"id":4041},"let-another-reviewer-inspect-the-decision","Let another reviewer inspect the decision",[11,4044,4045],{},"Give the reviewer the original sentence, proposed wording, exact source location, and reason for the change. Ask them to check the source itself and identify any part of the revised claim it still cannot support.",[11,4047,4048],{},"In the pilot example, they should be able to trace the narrower sentence to the observation and see why the causal claim was removed. Agreement between two reviewers is not proof of truth. If they disagree, record the disputed clause and the evidence or expertise needed to resolve it. The author then has a specific question to answer before that claim is ready.",{"title":326,"searchDepth":327,"depth":327,"links":4050},[4051,4052,4053,4054,4055],{"id":3864,"depth":327,"text":3865},{"id":3904,"depth":327,"text":3905},{"id":3976,"depth":327,"text":3977},{"id":4015,"depth":327,"text":4016},{"id":4041,"depth":327,"text":4042},"Check an AI-written claim against its source, work through a hypothetical example, and decide what to keep, qualify, remove, or send for specialist review.",{},"\u002Farticles\u002Fhow-to-fact-check-ai-generated-content","2026-07-26",[587,346,3349],[2497,4062],"how-to-refine-ai-agent-workflow",[353,1161],"Learn how to fact-check AI-generated content with a claim-level evidence review",{"title":3853,"description":4056},"articles\u002Fhow-to-fact-check-ai-generated-content",[4068,596,597],"fact-checking","Ii6IvSXGn6XovaHCQHk1mX5K29EWIb6r9HO5lBsjsug",{"id":4071,"title":4072,"author":6,"body":4073,"category":581,"description":4159,"extension":336,"featured":340,"heroImage":338,"meta":4160,"navigation":340,"path":4161,"publishedAt":4162,"readingTime":585,"relatedAgents":4163,"relatedArticles":4164,"relatedWorkflows":4165,"searchIntent":4166,"seo":4167,"stem":4168,"topics":4169,"updatedAt":179,"visual":362,"__hash__":4173},"articles\u002Farticles\u002Fai-workflow-automation.md","AI workflow automation: automate the rules, not the judgment",{"type":8,"value":4074,"toc":4154},[4075,4078,4081,4085,4088,4091,4094,4101,4105,4108,4111,4114,4117,4125,4138,4142,4145,4148,4151],[11,4076,4077],{},"Marking research complete can release the next agent to start writing. An unchecked completion flag can send it a result that is missing required material.",[11,4079,4080],{},"Before automating that transition, decide what must be checked and who can check it. Required fields and allowed actions can be enforced in code. An agent must interpret the evidence. A person may need to supply a choice or permission the workflow does not yet have.",[23,4082,4084],{"id":4083},"validate-the-result-before-advancing-the-step","Validate the result before advancing the step",[11,4086,4087],{},"A July 2026 StackOS content run exposed two problems in this boundary. Current workflow instructions could coexist with older cached plugin and resource contracts. The system also accepted successful step results without checking them against the step's output schema: the required fields, types, and structure.",[11,4089,4090],{},"The repair changed how the runtime refreshed those contracts when their source generation changed. It also added validation against the step's saved output schema before recording the state transition. In the live check of that July repair, a malformed result was rejected and the step stayed running. A corrected result then completed it.",[11,4092,4093],{},"Those responsibilities belong in the code that accepts a result. A prompt asking for every required field leaves the runtime free to accept an incomplete response. Validation has to happen before the workflow records success and releases dependent work.",[11,4095,4096,4097,4100],{},"For your own workflow, define the required output when you ",[15,4098,4099],{"href":410},"design the step",". Then try submitting a result with a required field missing. The system should identify that field and leave the step incomplete. This gives you a concrete way to check whether the completion rule is being enforced.",[23,4102,4104],{"id":4103},"a-valid-source-field-still-needs-an-evidence-decision","A valid source field still needs an evidence decision",[11,4106,4107],{},"Consider an illustrative research result with every required field present. It includes a proposed claim and a source reference. The source covers one tested configuration; the claim covers all configurations.",[11,4109,4110],{},"The structural check can pass while that mismatch remains. The agent assigned to evidence review needs to read the source in context and decide how far its support extends. Its return should identify the claim, the relevant source passage, and the decision: use a narrower statement, obtain more support, or leave the claim unresolved.",[11,4112,4113],{},"A schema can require a source ledger; it cannot decide which source resolves a contradiction. Make the evidence decision an explicit responsibility, with enough reasoning for the orchestrator to inspect. The runtime can require the review result before the next step proceeds. The orchestrator still has to determine whether the supported version serves the original request.",[11,4115,4116],{},"You can check this boundary separately from missing-field validation. Give the reviewer a structurally valid result containing the configuration mismatch above. A useful return names the unsupported scope and what must change. Returning another well-formed packet that simply says “supported” would leave the evidence decision unaccounted for.",[11,4118,4119,4120,4124],{},"The orchestrator's decision about ",[15,4121,4123],{"href":4122},"\u002Flibrary\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback\u002F","which reviewer findings become work"," belongs with this interpretation too. That guide develops the feedback decision without turning every comment into another delivery cycle.",[11,4126,4127,4128,4132,4133,4137],{},"These responsibilities can sit inside a straightforward sequence. ",[15,4129,4131],{"href":2955,"rel":4130},[19],"Anthropic's architecture guide"," distinguishes predefined workflow paths from agents that direct their process and tool use during the task. Microsoft's ",[15,4134,4136],{"href":2961,"rel":4135},[19],"orchestration guidance"," recommends the least complex approach that meets the requirements. For this example, research, review, and drafting can run in a fixed order while the review itself requires judgment about the sources.",[23,4139,4141],{"id":4140},"use-the-authority-already-supplied","Use the authority already supplied",[11,4143,4144],{},"Now suppose the draft includes a customer detail whose public use has not been authorized. The agent should identify the disclosure decision needed from the appropriate owner and keep that detail out of public output while it is unresolved. A relevant source and a completed research step supply no permission to disclose it.",[11,4146,4147],{},"The workflow should make the missing decision specific enough for that person to answer. Which detail would be shared, with whom, and for what purpose? Keep the request within the permitted private context. A broad “approve the workflow” question would leave the actual disclosure choice unclear.",[11,4149,4150],{},"An action and destination that the operator has already authorized require a different response. The agent should check that the planned action fits that authority and proceed when the required conditions are met. Preserve any approval that project policy requires; do not insert an additional confirmation merely because an agent performs the step.",[11,4152,4153],{},"Check both cases when evaluating the design. The case with missing disclosure permission should prevent the public action and identify the decision still needed. The already-authorized case should use the supplied permission, stay within its scope, and return evidence of the required result. If that case asks for the same permission again without a policy requirement, the workflow is ignoring a decision the operator has already made.",{"title":326,"searchDepth":327,"depth":327,"links":4155},[4156,4157,4158],{"id":4083,"depth":327,"text":4084},{"id":4103,"depth":327,"text":4104},{"id":4140,"depth":327,"text":4141},"Decide which workflow checks belong in code, which need an agent to interpret evidence, and when a person must supply missing intent or permission.",{},"\u002Farticles\u002Fai-workflow-automation","2026-07-12",[345,347,587],[589,2810,2811],[353,2500],"Learn how to automate AI workflows without hard-coding the judgment they need",{"title":4072,"description":4159},"articles\u002Fai-workflow-automation",[4170,4171,4172],"AI workflow automation","agent orchestration","workflow architecture","4avWwjUhaHAX3krQf7udPCIhmzNEZ_iOMAEz1iT_uwA",{"id":4175,"title":4176,"author":6,"body":4177,"category":581,"description":4405,"extension":336,"featured":340,"heroImage":338,"meta":4406,"navigation":340,"path":4407,"publishedAt":4162,"readingTime":2807,"relatedAgents":4408,"relatedArticles":4409,"relatedWorkflows":4411,"searchIntent":4412,"seo":4413,"stem":4414,"topics":4415,"updatedAt":361,"visual":362,"__hash__":4418},"articles\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback.md","How should an AI orchestrator triage feedback?",{"type":8,"value":4178,"toc":4399},[4179,4182,4185,4189,4192,4195,4216,4234,4252,4270,4288,4307,4310,4313,4316,4320,4323,4326,4334,4337,4342,4345,4348,4351,4355,4368,4371,4379,4386,4390,4393,4396],[11,4180,4181],{},"An unsupported claim and a request for a more dramatic introduction can arrive in the same review. Only one may need to stop the article.",[11,4183,4184],{},"The AI orchestrator has to inspect each finding against the current draft, the original request, and the evidence. Then it can tell the writer what to change, what to leave alone, and what still needs a decision.",[23,4186,4188],{"id":4187},"which-comments-become-work","Which comments become work?",[11,4190,4191],{},"Consider a hypothetical article explaining a team's proposed content-review process. The brief asks for a usable explanation and an example. Material claims need support, required links must work, the writing must follow the project's voice, and private details must stay out of the public copy.",[11,4193,4194],{},"The orchestrator has the brief, the current draft, the source notes, and these comments:",[428,4196,4201,4211],{"decision-label":4197,"evidence-label":4198,"label":4199,"record-heading":4200},"Decision for this draft","What the orchestrator checks","Unsupported claim","Reviewer finding",[435,4202,4203,4208],{"v-slot:evidence":326},[11,4204,4205],{},[31,4206,4207],{},"“Every claim is checked before publication” has no supporting evidence.",[11,4209,4210],{},"The source notes assign a separate reviewer to check material claims. They do not show that every claim was checked.",[435,4212,4213],{"v-slot:decision":326},[11,4214,4215],{},"Admit the finding. The unsupported statement blocks acceptance until it is supported, narrowed, or removed.",[428,4217,4219,4229],{"decision-label":4197,"evidence-label":4198,"label":4218,"record-heading":4200},"Wrong source link",[435,4220,4221,4226],{"v-slot:evidence":326},[11,4222,4223],{},[31,4224,4225],{},"A required source link points to the wrong page.",[11,4227,4228],{},"Open the destination and compare it with the intended source.",[435,4230,4231],{"v-slot:decision":326},[11,4232,4233],{},"Assign a local link repair and check the corrected destination.",[428,4235,4237,4247],{"decision-label":4197,"evidence-label":4198,"label":4236,"record-heading":4200},"Opening preference",[435,4238,4239,4244],{"v-slot:evidence":326},[11,4240,4241],{},[31,4242,4243],{},"The introduction would be more dramatic as a personal story.",[11,4245,4246],{},"Does the current opening leave the reader confused, break the brief, or conflict with the approved voice? In this example, it does none of those.",[435,4248,4249],{"v-slot:decision":326},[11,4250,4251],{},"Keep this as a preference. The writer does not need to invent a story or reopen the introduction.",[428,4253,4255,4265],{"decision-label":4197,"evidence-label":4198,"label":4254,"record-heading":4200},"Additional deliverable",[435,4256,4257,4262],{"v-slot:evidence":326},[11,4258,4259],{},[31,4260,4261],{},"Add a downloadable checklist.",[11,4263,4264],{},"Does the article need a separate file to deliver the explanation and example the operator requested? Here, it does not.",[435,4266,4267],{"v-slot:decision":326},[11,4268,4269],{},"Leave it outside this delivery. A useful additional deliverable still needs its own scope decision.",[428,4271,4273,4283],{"decision-label":4197,"evidence-label":4198,"label":4272,"record-heading":4200},"Stale finding",[435,4274,4275,4280],{"v-slot:evidence":326},[11,4276,4277],{},[31,4278,4279],{},"The draft contains a customer name.",[11,4281,4282],{},"Search the current candidate and inspect the quoted passage. The reviewer used an earlier version; the name is already gone.",[435,4284,4285],{"v-slot:decision":326},[11,4286,4287],{},"Reject the finding as stale, with the version and passage checked. Keep the current disclosure review.",[11,4289,4290,4291,4294,4295,4298,4299,4302,4303,4306],{},"These decisions use four practical terms: a ",[31,4292,4293],{},"blocker"," prevents acceptance, a ",[31,4296,4297],{},"repair"," is work to correct a defect, a ",[31,4300,4301],{},"preference"," is an optional choice, and ",[31,4304,4305],{},"out of scope"," describes work beyond the agreed delivery. A blocker can need a small repair. Calling it a blocker does not justify rewriting the whole article.",[11,4308,4309],{},"The labels are part of the method used here. What matters is the reason attached to each decision. “Critical” in a review report gives the orchestrator something to investigate; it does not settle whether the finding is valid.",[11,4311,4312],{},"Keep the original request beside the plan during that check. Suppose the plan omitted the example the operator asked for. A reviewer who points out the missing example has found a defect in the plan too. Correct the acceptance criteria and the article. A plan cannot make an unmet request disappear.",[11,4314,4315],{},"New evidence can also change the decision. A newly identified disclosure risk needs investigation even if nobody anticipated it when writing the brief.",[23,4317,4319],{"id":4318},"follow-the-unsupported-claim-through-a-repair","Follow the unsupported claim through a repair",[11,4321,4322],{},"The first finding in the queue has enough evidence to act on. Give it to the writer with the exact passage, the source mismatch, and a defined check for the return.",[11,4324,4325],{},"For this example, the record could be:",[689,4327,4332],{"className":4328,"code":4330,"language":4331,"meta":326},[4329],"language-yaml","candidate: draft-v3\npassage: \"Every claim is checked before publication.\"\nfailed_criterion: \"Material claims have support.\"\nevidence: \"Source notes specify a review task; no completed review is recorded.\"\ndecision: \"Admit; this statement blocks acceptance.\"\nrepair_owner: writer\nrepair: \"Describe the required review without claiming it has happened.\"\nverification: \"Independent claim reviewer compares the revision with the notes.\"\nstatus: open\n","yaml",[66,4333,4330],{"__ignoreMap":326},[11,4335,4336],{},"That request gives the writer room to solve the wording while keeping the factual boundary clear. A suitable replacement would be:",[42,4338,4339],{},[11,4340,4341],{},"Assign a separate reviewer to compare material claims with their sources before publication.",[11,4343,4344],{},"The sentence now gives the instruction the notes support. It makes no claim that the team has carried it out. The writer should also read the surrounding paragraph: removing one sentence would be insufficient if the next still promised that the process catches every error.",[11,4346,4347],{},"The claim reviewer checks the revised passage and its context against the notes. The orchestrator then records the version reviewed, the verification result, and whether the finding is resolved. The writer's report that it made the change starts that check; it does not finish it.",[11,4349,4350],{},"Keep the original finding in the record. If the repair fails, the next attempt needs to know which condition remains unmet. Replacing the finding with a vague “improve accuracy” comment would discard the useful part of the review.",[23,4352,4354],{"id":4353},"when-another-round-needs-a-decision","When another round needs a decision",[11,4356,4357,4358,4362,4363,4367],{},"Choose an iteration limit and a fallback before the review loop keeps going. ",[15,4359,4361],{"href":2955,"rel":4360},[19],"Anthropic's evaluator-optimizer guidance"," depends on clear evaluation criteria. Microsoft's ",[15,4364,4366],{"href":2961,"rel":4365},[19],"maker-checker guidance"," calls for acceptance criteria, an iteration cap, and fallback behavior. Set that limit for the task and the consequence of leaving a defect unresolved.",[11,4369,4370],{},"If the chosen limit is reached with an unsupported material claim still present, preserve the latest draft, attempted repairs, evidence, and unresolved criterion. Report that acceptance is still blocked. Writing “unresolved” beside the claim makes its status visible; it does not satisfy the requirement for supported copy.",[11,4372,4373,4374,4378],{},"Bring the operator a decision when the existing instructions cannot resolve it. That might be permission to disclose a detail, a missing fact only they can supply, or agreement to expand the deliverable. Explain ",[15,4375,4377],{"href":4376},"\u002Flibrary\u002Farticles\u002Fhow-ai-agents-should-explain-blockers-to-humans\u002F","what is blocked and which input is needed",". If two reviewers merely prefer different introductions and the current one meets the brief, the orchestrator already has enough to proceed.",[11,4380,4381,4382,4385],{},"This is the judgment involved in ",[15,4383,4170],{"href":4384},"\u002Flibrary\u002Farticles\u002Fai-workflow-automation\u002F",". A system can preserve a decision record and control which actions are permitted. The orchestrator still needs to decide whether the evidence warrants the change.",[23,4387,4389],{"id":4388},"close-against-the-revised-draft","Close against the revised draft",[11,4391,4392],{},"To finish the hypothetical queue, suppose the claim reviewer confirms that the revised instruction matches the notes and the surrounding paragraph contains no remaining outcome promise. The corrected link opens the intended source. The current candidate also passes the required voice and disclosure checks and contains the usable explanation and example the operator requested.",[11,4394,4395],{},"Record those checks against that candidate and close the two admitted repairs. The stale finding has its rejection reason. The more dramatic opening remains a preference, and the separate checklist remains outside the delivery.",[11,4397,4398],{},"The article is ready under the agreed criteria. The review record still contains ideas that were not used.",{"title":326,"searchDepth":327,"depth":327,"links":4400},[4401,4402,4403,4404],{"id":4187,"depth":327,"text":4188},{"id":4318,"depth":327,"text":4319},{"id":4353,"depth":327,"text":4354},{"id":4388,"depth":327,"text":4389},"Work through a mixed review queue to decide which findings need a repair, who should make it, and what to check before calling the work complete.",{},"\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback",[587,848,2495],[589,2810,4410],"ai-workflow-automation",[353,2500],"Learn how an AI orchestrator should evaluate reviewer feedback without allowing scope drift",{"title":4176,"description":4405},"articles\u002Fhow-ai-orchestrators-triage-feedback",[4416,4417,4171],"AI orchestrators","feedback triage","S0RWdn16w_jxhX3ovU22PJnRQrbjAu57T_9b8obkgHY",{"id":4420,"title":4421,"author":6,"body":4422,"category":581,"description":4754,"extension":336,"featured":340,"heroImage":338,"meta":4755,"navigation":340,"path":4756,"publishedAt":4162,"readingTime":2492,"relatedAgents":4757,"relatedArticles":4758,"relatedWorkflows":4759,"searchIntent":4760,"seo":4761,"stem":4762,"topics":4763,"updatedAt":4767,"visual":4768,"__hash__":4769},"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":4423,"toc":4747},[4424,4427,4430,4433,4437,4443,4446,4449,4452,4456,4459,4462,4465,4471,4474,4477,4480,4489,4493,4496,4499,4525,4528,4531,4534,4537,4552,4565,4578,4591,4604,4607,4614,4618,4621,4624,4627,4630,4700,4703,4706,4710,4713,4716,4733,4736,4744],[11,4425,4426],{},"After the first successful run, I want to know what the next agent will have to figure out for itself.",[11,4428,4429],{},"I ask an agent to manage that refinement. It sends fresh subagents through the workflow, collects their feedback, and questions them after they finish. Where did they hesitate? What did they have to infer? Which workaround affected the result?",[11,4431,4432],{},"The coordinating agent compares those accounts with what actually happened and decides which findings deserve a change. That gives me a practical way to investigate the workflow without personally reviewing every step or accepting every suggestion an agent produces.",[23,4434,4436],{"id":4435},"keep-the-result-youre-trying-to-preserve","Keep the result you're trying to preserve",[11,4438,4439,4440,190],{},"Refinement starts with a workflow that has completed a representative task. If you're still deciding what it should do, start with ",[15,4441,4442],{"href":410},"defining the workflow",[11,4444,4445],{},"Save the successful task and its evidence alongside the goal, scope, constraints, acceptance criteria, and stopping condition. The next run needs a stable comparison. Otherwise, a reviewer can quietly replace the agreed result with whatever it would prefer to see.",[11,4447,4448],{},"Make completion observable. For an article workflow, that might mean the draft is saved, its material claims have support, blocking review findings are resolved, and disclosure review has passed. “The article is good” leaves too much for each runner to invent.",[11,4450,4451],{},"Keep those conditions steady during the trial. If the goal changes, record that decision and establish a new baseline before comparing results.",[23,4453,4455],{"id":4454},"give-fresh-agents-a-normal-task","Give fresh agents a normal task",[11,4457,4458],{},"The refinement agent coordinates the trials. Each runner gets the task, normal project context, available tools, and permission boundaries. It should be able to work from what the workflow supplies.",[11,4460,4461],{},"Keep the suspected defect and private debugging history out of the runner's brief. You want to see where the ordinary path takes it. An instruction that tells it exactly which failure to look for changes that test.",[11,4463,4464],{},"For a content workflow, put a concrete article request above a prompt like this:",[689,4466,4469],{"className":4467,"code":4468,"language":694,"meta":326},[692],"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 blocked.\nReturn the result, its supporting records, and any unresolved work.\n",[66,4470,4468],{"__ignoreMap":326},[11,4472,4473],{},"A trial still has to respect the limits on real work. Use fixtures or an isolated environment when a run would otherwise change real records. Reset the relevant state between trials so one runner doesn't inherit another's finished work.",[11,4475,4476],{},"Ask the coordinator to retain the instruction, workflow version, starting state, final result, and supporting records for each run. Keep the trace of tool calls and results, including retries, workarounds, and any incorrect state change. Those records let it check a runner's account later.",[11,4478,4479],{},"Choose trials according to the question. Repeating a task tests consistency; using different representative tasks tests whether the workflow handles those variations. Scale the effort to the cost of a run and the consequence of failure. A successful attempt gives you one observed success; it doesn't establish how often the workflow will succeed.",[11,4481,4482,4483,4488],{},"Anthropic's ",[15,4484,4487],{"href":4485,"rel":4486},"https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fdemystifying-evals-for-ai-agents",[19],"guide to agent evaluations"," separates the task, each trial, the agent's trace, and the resulting environment state. It also recommends isolating trials and building early evaluations from real failures and existing manual checks. Those distinctions help keep a convincing completion message from standing in for the result you're meant to verify.",[23,4490,4492],{"id":4491},"ask-what-happened-while-the-run-is-still-in-context","Ask what happened while the run is still in context",[11,4494,4495],{},"After a run, I ask the agent about the decisions and friction it encountered. The trace gives us the actions to inspect; the debrief gives us leads about why the agent took them.",[11,4497,4498],{},"These are the questions I want answered:",[138,4500,4501,4504,4507,4510,4513,4516,4519,4522],{},[141,4502,4503],{},"Where did you hesitate or have to investigate before you could continue?",[141,4505,4506],{},"Which decision did you make that the workflow did not clearly resolve?",[141,4508,4509],{},"What context did you need but not receive at the point of use?",[141,4511,4512],{},"Was any tool difficult to find, understand, or call correctly?",[141,4514,4515],{},"What workaround did you use?",[141,4517,4518],{},"Did the friction threaten the final outcome, or did it only add effort?",[141,4520,4521],{},"What part of the workflow was clearer than expected?",[141,4523,4524],{},"If you changed one generic thing for the next agent, what would it be? What would you leave alone?",[11,4526,4527],{},"Keep each runner's answers independent until they are recorded. The coordinator can conduct the debriefs itself or delegate those conversations to another agent. The agent collecting answers returns the evidence; the coordinator owns the decision about changes.",[11,4529,4530],{},"Then check the answers against the run. Suppose a runner reports that a required source was missing. Inspect the context it received, the source references it could retrieve, and the calls it made. Was the source absent? Was the reference broken? Did the agent overlook a usable reference? The same complaint can lead to different repairs.",[11,4532,4533],{},"Ask for the consequence too. If the agent guessed a material fact, inspect that fact and the result that depended on it. If it spent time finding the right document and still met the criteria, decide whether that delay matters enough to change the workflow. A runner's explanation is useful evidence to investigate, but it cannot prove the cause by itself.",[11,4535,4536],{},"The coordinator can sort the findings by what they mean for the work:",[428,4538,4542,4547],{"decision-label":1085,"evidence-label":4539,"label":4540,"record-heading":4541},"What makes it actionable?","Blocking defect","Finding",[435,4543,4544],{"v-slot:evidence":326},[11,4545,4546],{},"An accepted criterion fails, a hard constraint is violated, or state advances incorrectly.",[435,4548,4549],{"v-slot:decision":326},[11,4550,4551],{},"Repair before accepting the run.",[428,4553,4555,4560],{"decision-label":1085,"evidence-label":4539,"label":4554,"record-heading":4541},"Bounded repair",[435,4556,4557],{"v-slot:evidence":326},[11,4558,4559],{},"A specific correction within the agreed scope would restore the required result.",[435,4561,4562],{"v-slot:decision":326},[11,4563,4564],{},"Assign it to the responsible owner with a verification check.",[428,4566,4568,4573],{"decision-label":1085,"evidence-label":4539,"label":4567,"record-heading":4541},"Normal friction",[435,4569,4570],{"v-slot:evidence":326},[11,4571,4572],{},"Investigation or recovery added effort, while the result and constraints still passed.",[435,4574,4575],{"v-slot:decision":326},[11,4576,4577],{},"Record the consequence; change it only if that consequence warrants the work.",[428,4579,4581,4586],{"decision-label":1085,"evidence-label":4539,"label":4580,"record-heading":4541},"Preference",[435,4582,4583],{"v-slot:evidence":326},[11,4584,4585],{},"A reviewer favors another approach without identifying a failed criterion.",[435,4587,4588],{"v-slot:decision":326},[11,4589,4590],{},"Leave it out of the current repair.",[428,4592,4594,4599],{"decision-label":1085,"evidence-label":4539,"label":4593,"record-heading":4541},"Scope change",[435,4595,4596],{"v-slot:evidence":326},[11,4597,4598],{},"The suggestion changes the goal, audience, capability, or delivery boundary.",[435,4600,4601],{"v-slot:decision":326},[11,4602,4603],{},"Return it for a separate scope decision.",[11,4605,4606],{},"Repeated findings help the coordinator see a pattern. A single invalid state transition can already be enough to require a repair. Count and consequence answer different questions.",[11,4608,4609,4610,4613],{},"The broader ",[15,4611,4612],{"href":4122},"feedback-triage guide"," covers that decision boundary. Here, keep each admitted finding tied to the observed failure, the criterion it threatens, and the evidence needed to check a correction.",[23,4615,4617],{"id":4616},"follow-the-failure-to-the-layer-that-owns-it","Follow the failure to the layer that owns it",[11,4619,4620],{},"In a July 2026 StackOS content run, the runtime allowed mixed generations of contracts: a current workflow could coexist with cached older plugin and resource schemas. It also accepted successful step results without checking them against the output schema frozen for that step.",[11,4622,4623],{},"That gave the repair a specific target. We made contract synchronization account for generation changes and added result validation before the state transition. In the subsequent live check, a malformed result was rejected while the step stayed open. A corrected result then completed it.",[11,4625,4626],{},"Telling the agent to be more careful would have left both runtime faults in place. The useful change was in how contracts were refreshed and results were checked.",[11,4628,4629],{},"Use the same reasoning when the symptom is less obvious:",[928,4631,4632,4642],{},[931,4633,4634],{},[934,4635,4636,4639],{},[937,4637,4638],{},"What the evidence shows",[937,4640,4641],{},"Where to investigate",[947,4643,4644,4652,4660,4668,4676,4684,4692],{},[934,4645,4646,4649],{},[952,4647,4648],{},"Runners disagree about what completion requires.",[952,4650,4651],{},"The goal, acceptance criteria, or stopping condition.",[934,4653,4654,4657],{},[952,4655,4656],{},"One step's output doesn't supply what the next step needs.",[952,4658,4659],{},"Step boundaries, dependencies, and output contracts.",[934,4661,4662,4665],{},[952,4663,4664],{},"A specialist has to guess a fact already established earlier.",[952,4666,4667],{},"The context and source references passed to that specialist.",[934,4669,4670,4673],{},[952,4671,4672],{},"The right operation exists, but the agent cannot find or call it correctly.",[952,4674,4675],{},"Tool selection, descriptions, schemas, and usage guidance.",[934,4677,4678,4681],{},[952,4679,4680],{},"Invalid output changes state, or cached contracts conflict.",[952,4682,4683],{},"Runtime validation and contract synchronization.",[934,4685,4686,4689],{},[952,4687,4688],{},"Sufficient inputs and tools are present, but the agent makes a poor decision.",[952,4690,4691],{},"The role guidance, examples, and evaluation criteria.",[934,4693,4694,4697],{},[952,4695,4696],{},"A necessary provider or local service is unavailable.",[952,4698,4699],{},"The environment and permitted recovery steps.",[11,4701,4702],{},"For each proposed repair, ask what replay would distinguish a fix from another lucky pass. If the problem is a missing source handoff, the next runner should receive and use the source without the old workaround. If malformed output was accepted, deliberately submitting malformed output should leave the step incomplete.",[11,4704,4705],{},"Change one cause at a time where practical. Editing the prompt, tool interface, and runtime together makes it harder to tell which correction mattered. Keep the original failure as a regression case so later changes can be checked against it.",[23,4707,4709],{"id":4708},"check-the-repair-with-another-fresh-run","Check the repair with another fresh run",[11,4711,4712],{},"Give a fresh agent the normal task and the revised workflow. Keep the original acceptance criteria and ask the same debrief questions. The runner should be able to complete the task without needing the private explanation from the investigation.",[11,4714,4715],{},"Compare the evidence before and after:",[228,4717,4718,4721,4724,4727,4730],{},[141,4719,4720],{},"Did the required result appear in the intended environment?",[141,4722,4723],{},"Did the specific failure that prompted the repair recur?",[141,4725,4726],{},"Where applicable, was invalid output rejected before state changed?",[141,4728,4729],{},"Did the agent still need the consequential guess or workaround?",[141,4731,4732],{},"Did the workflow stop when the agreed result was ready?",[11,4734,4735],{},"If the output passes but the runner still makes the same unsupported guess, inspect what happened. The passing output alone doesn't establish that the diagnosed problem is gone.",[11,4737,4738,4739,4743],{},"Set a limit on the refinement loop and decide what happens when it is reached. Microsoft's ",[15,4740,4742],{"href":2961,"rel":4741},[19],"agent orchestration guidance"," recommends explicit acceptance criteria, an iteration cap, and a fallback for maker-checker loops. For this method, that fallback can be a return to the operator with the failed criterion, attempts made, and unresolved decision.",[11,4745,4746],{},"When the chosen trials satisfy the criteria, retain the tested version, tasks, results, and remaining limits. Close the repair on that evidence. Another agent may still have a suggestion; it needs its own reason to become work.",{"title":326,"searchDepth":327,"depth":327,"links":4748},[4749,4750,4751,4752,4753],{"id":4435,"depth":327,"text":4436},{"id":4454,"depth":327,"text":4455},{"id":4491,"depth":327,"text":4492},{"id":4616,"depth":327,"text":4617},{"id":4708,"depth":327,"text":4709},"Refine a working AI agent workflow with fresh agent trials, post-run debriefs, trace checks, and bounded repairs. Includes a prompt and questions to use.",{},"\u002Farticles\u002Fhow-to-refine-ai-agent-workflow",[587,848,2495],[589,2810,2497],[353,2500],"Learn how to test, refine, and polish an AI agent workflow after the first version works",{"title":4421,"description":4754},"articles\u002Fhow-to-refine-ai-agent-workflow",[4764,4765,4766],"AI agent workflows","workflow refinement","agent evaluation","2026-09-30","workflow","ZWGD4JUnsm3Ep68JjqCSpeDJ3pvytw_3fVyO3-mYGBg",{"id":4771,"title":4772,"author":6,"body":4773,"category":581,"description":4977,"extension":336,"featured":340,"heroImage":338,"meta":4978,"navigation":340,"path":4979,"publishedAt":4162,"readingTime":2807,"relatedAgents":4980,"relatedArticles":4982,"relatedWorkflows":4983,"searchIntent":4984,"seo":4985,"stem":4986,"topics":4987,"updatedAt":361,"visual":4768,"__hash__":4991},"articles\u002Farticles\u002Fwhat-ai-agent-handoff-should-include.md","What should an AI agent handoff include?",{"type":8,"value":4774,"toc":4969},[4775,4778,4781,4784,4788,4791,4841,4845,4852,4855,4858,4864,4867,4870,4874,4877,4886,4889,4893,4896,4899,4902,4905,4909,4912,4925,4933,4937,4940,4960,4963,4966],[11,4776,4777],{},"Suppose an agent prepares a new version of a shared file, sends the update, and loses the connection before the response arrives. Another agent takes over.",[11,4779,4780],{},"The local file is ready. The remote file may already have changed. The next agent needs to know both before deciding what to do.",[11,4782,4783],{},"An AI agent handoff should carry the objective, accepted state and evidence, relevant context, authority and tools, required output, acceptance criteria, recovery guidance, and a destination and stopping rule. Together, these tell the receiver what finished, what remains uncertain, and which action it can take next.",[23,4785,4787],{"id":4786},"eight-fields-for-a-useful-handoff","Eight fields for a useful handoff",[11,4789,4790],{},"Stable instructions can stay in referenced project records. Resolve the parts that matter to the current task:",[228,4792,4793,4799,4805,4811,4817,4823,4829,4835],{},[141,4794,4795,4798],{},[31,4796,4797],{},"Objective and ownership:"," the task to perform now and who owns the next decision.",[141,4800,4801,4804],{},[31,4802,4803],{},"Accepted state and evidence:"," current inputs, settled decisions, completed work, unresolved results and supporting records.",[141,4806,4807,4810],{},[31,4808,4809],{},"Context and policies:"," the relevant history and rules for this step.",[141,4812,4813,4816],{},[31,4814,4815],{},"Authority and tools:"," permitted operations, their targets and the changes the receiver may make.",[141,4818,4819,4822],{},[31,4820,4821],{},"Required output:"," the result, fields or artifact to return, including evidence.",[141,4824,4825,4828],{},[31,4826,4827],{},"Acceptance criteria:"," what must be true for this responsibility to be complete.",[141,4830,4831,4834],{},[31,4832,4833],{},"Recovery guidance:"," what to do when an input or operation is missing, fails or leaves an uncertain result.",[141,4836,4837,4840],{},[31,4838,4839],{},"Destination and stopping rule:"," where to return the result and when to stop.",[23,4842,4844],{"id":4843},"a-packet-for-the-interrupted-update","A packet for the interrupted update",[11,4846,49,4847,4851],{},[15,4848,4850],{"href":4849},"\u002Fexamples\u002Fwhat-ai-agent-handoff-should-include\u002Finterrupted-update.yaml","complete example packet"," puts those fields together. It is hypothetical YAML with placeholder references, not a StackOS API payload. Replace its operations and references with ones your tools support.",[11,4853,4854],{},"In this example, the local document passed its checks and was approved. The file service supports looking up the timed-out request by its saved identifier and reading the remote file's current version and contents. The receiving agent may perform those reads; it may not send another update or edit the approved file.",[11,4856,4857],{},"The packet starts with the approved file, its content fingerprint, checks and approval records, the target and the attempted request. This excerpt makes the unresolved state explicit:",[689,4859,4862],{"className":4860,"code":4861,"language":4331,"meta":326},[4329],"accepted_state:\n  local_result: >-\n    Timed out before\n    receiving the\n    response.\n  external_result: >-\n    Unconfirmed.\n\nstop_when: >-\n  The permitted checks\n  are complete or a\n  required check\n  is blocked.\n",[66,4863,4861],{"__ignoreMap":326},[11,4865,4866],{},"A timeout tells you that the caller stopped waiting. It does not establish whether the service applied the change. The receiver must inspect the request and file before the coordinating agent can decide what happens next.",[11,4868,4869],{},"The full packet asks for the observed request status, remote version, content comparison and supporting records. Missing, pending, partial or conflicting evidence stays visible in the return. The stopping rule lets the receiver finish a bounded check without pretending that the file-update task is finished too.",[23,4871,4873],{"id":4872},"say-who-owns-the-next-decision","Say who owns the next decision",[11,4875,4876],{},"“Act as an editor” names a role. “Review the supplied article for unsupported material claims and return findings to the coordinating agent” gives the editor a task and a destination. Add whether it may repair the article or should return findings. An editing tool's availability cannot decide that.",[11,4878,4879,4880,4885],{},"Handoff also means different things across architectures. Microsoft's ",[15,4881,4884],{"href":4882,"rel":4883},"https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fagent-framework\u002Fworkflows\u002Forchestrations\u002Fhandoff",[19],"handoff orchestration"," transfers control and task ownership to the receiving agent. Its agents-as-tools pattern leaves responsibility with the primary agent, which receives the specialist's result.",[11,4887,4888],{},"Our file-checking agent returns evidence. The coordinating agent still owns the update and any decision to try again. The original writer's permission does not silently give its successor permission to retry or act on another file.",[23,4890,4892],{"id":4891},"keep-the-evidence-and-settled-decisions-together","Keep the evidence and settled decisions together",[11,4894,4895],{},"“Use the latest file” leaves the receiver to discover which version was approved and whether it has changed. A stable reference, revision or content fingerprint gives it something to check.",[11,4897,4898],{},"For the interrupted update, retain three separate records: the approved local file and its checks, the attempted request to the named target, and any evidence about the external result. A note saying “checks passed” needs the result for that file version. An approval needs to identify what was approved.",[11,4900,4901],{},"The approved content remains the intended update while the receiver investigates. Rewriting it would change the comparison the check depends on. If new evidence calls that decision into question, return the finding to its owner.",[11,4903,4904],{},"Put each permitted operation beside its purpose and target. Here, request lookup establishes the attempted operation's status, while reading the file establishes what is currently there. Neither a sent request nor a filled-in result form is proof that the requested update completed.",[23,4906,4908],{"id":4907},"choose-context-the-receiver-can-use","Choose context the receiver can use",[11,4910,4911],{},"Include context when it changes the next action or judgment. The approved file, target, request history and rules for checking the remote result matter here. Discussion of a discarded draft can remain retrievable.",[11,4913,49,4914,4919,4920,4924],{},[15,4915,4918],{"href":4916,"rel":4917},"https:\u002F\u002Fopenai.github.io\u002Fopenai-agents-python\u002Fhandoffs\u002F",[19],"OpenAI Agents SDK"," separates model-generated handoff arguments from local application context. Those arguments do not replace the receiving agent's main input, and input filters can change the history it sees. Microsoft's ",[15,4921,4923],{"href":2961,"rel":4922},[19],"agent design guidance"," likewise distinguishes full, compacted and new context, and recommends durable external state for work across interruptions. Choose what the task needs; a shorter packet is useful only if the receiver can still recover necessary detail.",[11,4926,4927,4928,4932],{},"In StackOS, a claimed step includes its instructions, expected outputs, allowed tools and bounded results from direct predecessor steps. When a predecessor result is too large for the handoff, the response provides a targeted read for the complete result. The ",[15,4929,4931],{"href":4930},"\u002Flibrary\u002Farticles\u002Fai-agent-experience\u002F","agent-experience guide"," covers context, tools and recovery across the workflow.",[23,4934,4936],{"id":4935},"return-the-outcome-the-evidence-supports","Return the outcome the evidence supports",[11,4938,4939],{},"The packet gives the receiver three possible conclusions:",[228,4941,4942,4948,4954],{},[141,4943,4944,4947],{},[31,4945,4946],{},"The request completed and the target matches the approved content."," Return the completion record and file comparison. The coordinating agent can record the update as complete without another write.",[141,4949,4950,4953],{},[31,4951,4952],{},"A terminal request record proves that no change occurred."," Return that record and the observed file state. The coordinating agent can decide whether a retry is appropriate under the provider's behavior and current authorization.",[141,4955,4956,4959],{},[31,4957,4958],{},"The evidence is incomplete or conflicts."," Return the precise unresolved result. A matching remote file can establish that the desired content is present, but a missing request record may still leave the attempted operation unaccounted for. A pending request, partial change or different file version also needs its own next decision.",[11,4961,4962],{},"The recovery instructions say what to return if an input is unavailable, a read fails, a request is pending or records conflict. The receiver does not substitute another write for a check it could not complete.",[11,4964,4965],{},"To inspect the packet, give it to a fresh agent and ask what it would do first. It should identify the local evidence and permitted request lookup. If it proposes uploading again, check whether it missed the authority boundary or the packet left the external state ambiguous.",[11,4967,4968],{},"When evidence remains missing, the receiving agent can finish its check while the file-update task stays open. Its return should make the next missing check or decision clear.",{"title":326,"searchDepth":327,"depth":327,"links":4970},[4971,4972,4973,4974,4975,4976],{"id":4786,"depth":327,"text":4787},{"id":4843,"depth":327,"text":4844},{"id":4872,"depth":327,"text":4873},{"id":4891,"depth":327,"text":4892},{"id":4907,"depth":327,"text":4908},{"id":4935,"depth":327,"text":4936},"Build an AI agent handoff with the objective, evidence, context, tools, expected result, and stopping rule. See how to continue after an interrupted update.",{},"\u002Farticles\u002Fwhat-ai-agent-handoff-should-include",[4981,347,587],"stackos-sdlc-delivery",[2810,589,2497],[353,2500],"Learn what an AI agent handoff packet should contain",{"title":4772,"description":4977},"articles\u002Fwhat-ai-agent-handoff-should-include",[4988,4989,4990],"AI agent handoffs","agent context","multi-agent workflows","99SUPQVreAgy2AaIrZaURRdsfJ9_EsAQpLus7rhyiSk",{"id":4993,"title":4994,"author":6,"body":4995,"category":581,"description":5211,"extension":336,"featured":340,"heroImage":338,"meta":5212,"navigation":340,"path":5213,"publishedAt":5214,"readingTime":2807,"relatedAgents":5215,"relatedArticles":5216,"relatedWorkflows":5218,"searchIntent":5219,"seo":5220,"stem":5221,"topics":5222,"updatedAt":5226,"visual":362,"__hash__":5227},"articles\u002Farticles\u002Fai-agent-experience.md","Agent experience: the missing layer in AI agent orchestration",{"type":8,"value":4996,"toc":5204},[4997,5000,5003,5006,5010,5013,5027,5032,5050,5055,5063,5069,5075,5081,5084,5088,5105,5108,5111,5136,5139,5147,5150,5154,5157,5160,5163,5166,5169,5177,5181,5184,5187,5190,5194,5201],[11,4998,4999],{},"“Review the implementation” leaves the agent a second job: work out what it is supposed to review.",[11,5001,5002],{},"Which version, against which requirements, with permission to do what? The coordinating agent may already know those answers. If the assignment leaves them out, the reviewer has to search for them, ask, or guess before it can begin.",[11,5004,5005],{},"Agent experience is the work an agent must do to understand and carry out its assigned step. You can inspect it through the inputs it receives, the actions available to it, and what happens when something is missing. Start at the moment the assignment arrives.",[23,5007,5009],{"id":5008},"replace-the-vague-request-with-something-usable","Replace the vague request with something usable",[11,5011,5012],{},"Here is a small, self-contained exercise. The task is to review a Python function that checks a file count. Everything needed for this review is below; there is no repository or hidden test fixture to discover.",[11,5014,5015,5018,5019,5022,5023,5026],{},[31,5016,5017],{},"Task:"," compare ",[66,5020,5021],{},"candidate-v1"," with ",[66,5024,5025],{},"requirements-v1"," and return a review to the coordinating agent.",[11,5028,5029],{},[31,5030,5031],{},"Requirements, version 1:",[228,5033,5034,5037,5044],{},[141,5035,5036],{},"The input is an integer. Type handling is outside this exercise.",[141,5038,5039,5040,5043],{},"Return ",[66,5041,5042],{},"True"," for a count from 1 through 5, inclusive.",[141,5045,5039,5046,5049],{},[66,5047,5048],{},"False"," for every other integer, including zero and negative values.",[11,5051,5052],{},[31,5053,5054],{},"Candidate, version 1:",[689,5056,5061],{"className":5057,"code":5059,"language":5060,"meta":326},[5058],"language-python","def valid_file_count(count):\n    return 0 \u003C= count \u003C= 5\n","python",[66,5062,5059],{"__ignoreMap":326},[11,5064,5065,5068],{},[31,5066,5067],{},"Scope:"," inspect the supplied requirement and code. This review needs no tools. Do not run the code, edit it, install anything, search a repository, or contact an external service.",[11,5070,5071,5074],{},[31,5072,5073],{},"Return:"," name the requirement and candidate versions reviewed, say whether the candidate meets the rule, and give the evidence for any discrepancy. Include the input that exposes it, the expected result, the result implied by the code, and the relevant expression. State the method used and any check not performed.",[11,5076,5077,5080],{},[31,5078,5079],{},"Stop:"," return that review to the coordinating agent. Any code change belongs to a subsequent assignment. If the required input is missing in an adaptation of this exercise, identify the missing version and the check it prevents; do not substitute another version or invent a requirement.",[11,5082,5083],{},"That is the whole assignment. In a real system, configure the host's available tools and permissions to match its scope. The instruction to avoid edits is useful guidance, but it does not itself remove a write capability.",[23,5085,5087],{"id":5086},"follow-the-receivers-first-action","Follow the receiver's first action",[11,5089,5090,5091,5094,5095,5097,5098,5101,5102,5104],{},"The reviewer can begin by comparing the permitted range with the expression. At ",[66,5092,5093],{},"count = 0",", the requirement says ",[66,5096,5048],{},", while ",[66,5099,5100],{},"0 \u003C= count \u003C= 5"," evaluates to ",[66,5103,5042],{},". The lower bound is wrong.",[11,5106,5107],{},"The other boundaries help delimit the finding. Counts 1 and 5 satisfy both the requirement and the expression. Negative integers and values greater than 5 are excluded by the expression. For the stated integer input, zero is the discrepancy.",[11,5109,5110],{},"A useful return could be:",[42,5112,5113],{},[11,5114,5115,5116,5118,5119,5121,5122,5125,5126,5128,5129,5132,5133,5135],{},"Reviewed ",[66,5117,5021],{}," against ",[66,5120,5025],{}," by inspection. The candidate does not meet the count rule: for input ",[66,5123,5124],{},"0",", the required result is ",[66,5127,5048],{},", but ",[66,5130,5131],{},"0 \u003C= 0 \u003C= 5"," is ",[66,5134,5042],{},". The lower bound admits zero. Code was not executed or changed. No required input was missing.",[11,5137,5138],{},"This is the expected reasoning for the exercise, not a report from an executed agent trial. It gives the coordinator enough to inspect the finding and assign a repair. The reviewer has completed its part while the implementation still fails a requirement.",[11,5140,5141,5142,5146],{},"That separation matters when assigning an ",[15,5143,5145],{"href":5144},"\u002Flibrary\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator\u002F","AI agent, workflow, and orchestrator"," their responsibilities. Here the reviewer supplies evidence; the coordinator decides what happens to delivery. Quietly changing the function would make the return about different code from the version the reviewer was asked to inspect.",[11,5148,5149],{},"You can try the assignment with a fresh agent. Give it the assignment above without the worked answer, then inspect its actual return. Did it compare the supplied versions, identify zero, explain the discrepancy, state that it used inspection, and stop without editing? If it starts searching for a repository, find out whether the packet was incomplete, the tool setup was misleading, or the agent overlooked the supplied input. Record what happened before choosing a repair.",[23,5151,5153],{"id":5152},"select-context-for-the-work-at-hand","Select context for the work at hand",[11,5155,5156],{},"The example is small enough to include every relevant input. A real review may need source files, requirements, test instructions, project rules, and earlier decisions. Resolve those references before dispatch where the workflow already knows which ones apply.",[11,5158,5159],{},"A directory containing several drafts still leaves the reviewer to choose an authoritative version. An exact candidate reference and the applicable requirement resolve that choice. Keep additional history available when the task may need it, with a clear way to retrieve it.",[11,5161,5162],{},"Context is useful when it reduces uncertainty. Beyond that point, it becomes another search surface.",[11,5164,5165],{},"StackOS documents its claimed-step packet around this distinction: the active instructions, resolved inputs, selected context, expected outputs, allowed tools, and bounded results from direct predecessor steps. If supplied material is truncated, the documented response includes a targeted read for the full step result. That is a recovery path the receiver can follow without reconstructing where the input came from.",[11,5167,5168],{},"For your own assignments, name the recovery action that fits the gap. A missing requirement needs its reference or a decision from its owner. An unavailable test command needs a report of the check it prevents. The reviewer should not silently replace either with a guess. A good recovery path narrows the next decision without pretending every failure can be anticipated.",[11,5170,5171,5172,5176],{},"An ",[15,5173,5175],{"href":5174},"\u002Flibrary\u002Farticles\u002Fwhat-is-an-agentic-workflow\u002F","agentic workflow"," can choose later work from these findings. The current receiver still needs enough information to perform its own assignment and return control.",[23,5178,5180],{"id":5179},"what-one-stackos-replay-recorded","What one StackOS replay recorded",[11,5182,5183],{},"In a July 2026 StackOS foundation replay, a draft specialist reported needing no tools and no guessing for its bounded assignment. The same step record described its work as slow. Elsewhere, the replay notes recorded a fresh subagent missing its allotted execution window. A complete packet and an easy or fast run are separate things to investigate.",[11,5185,5186],{},"Another step's saved report says it recovered a truncated handoff through a targeted read of the prior result. The final step instructed the agent to return the handoff and stop. Its terminal record reports that the run ended without starting the next workflow, changing that workflow's setup, or creating content.",[11,5188,5189],{},"These records preserve the agents' reports and the stopping instruction. They do not isolate what caused the reported behavior. The useful evidence is specific: what the receiver said it needed, how it reported recovering missing material, where it stopped, and which friction remained.",[23,5191,5193],{"id":5192},"put-a-missing-decision-where-the-next-agent-can-find-it","Put a missing decision where the next agent can find it",[11,5195,5196,5197,5200],{},"When ",[15,5198,5199],{"href":410},"building an AI agent workflow",", inspect the receiver's searches and questions alongside the work it was assigned. Investigating an undocumented behavior may be the substance of a review. Locating the approved requirement is avoidable reconstruction when the coordinator already selected it.",[11,5202,5203],{},"The file-count reviewer still has to reason about the comparison. The assignment supplies the rule, candidate, authority, and destination so that reasoning has a clear object. If a real reviewer has to ask which range was approved, put the answer and its source into the next assignment. Then it can spend its effort checking whether the code satisfies that rule.",{"title":326,"searchDepth":327,"depth":327,"links":5205},[5206,5207,5208,5209,5210],{"id":5008,"depth":327,"text":5009},{"id":5086,"depth":327,"text":5087},{"id":5152,"depth":327,"text":5153},{"id":5179,"depth":327,"text":5180},{"id":5192,"depth":327,"text":5193},"Turn a vague review request into an assignment an agent can carry out. See how exact inputs, authority, evidence, recovery, and a stopping rule fit together.",{},"\u002Farticles\u002Fai-agent-experience","2026-07-11",[347,587,848],[5217,2811,589],"ai-agent-vs-workflow-vs-orchestrator",[353,2500],"Understand how to design the operating experience inside AI agent orchestration",{"title":4994,"description":5211},"articles\u002Fai-agent-experience",[5223,5224,5225],"AI agent orchestration","agent experience","workflow design","2026-10-04","wbcBygSmX7vmqbmWxlIxrNDGdbO7PCc-MBZHa2K2Hp8",{"id":5229,"title":5230,"author":6,"body":5231,"category":581,"description":5546,"extension":336,"featured":340,"heroImage":338,"meta":5547,"navigation":340,"path":5548,"publishedAt":5214,"readingTime":343,"relatedAgents":5549,"relatedArticles":5551,"relatedWorkflows":5552,"searchIntent":5553,"seo":5554,"stem":5555,"topics":5556,"updatedAt":361,"visual":362,"__hash__":5557},"articles\u002Farticles\u002Fhow-to-build-ai-agent-workflow.md","How to build an AI agent workflow: start with the problem",{"type":8,"value":5232,"toc":5537},[5233,5236,5239,5243,5246,5249,5252,5256,5259,5266,5269,5341,5347,5351,5354,5398,5401,5406,5409,5412,5426,5429,5433,5436,5448,5451,5454,5460,5464,5467,5473,5476,5479,5482,5488,5494,5497,5501,5504,5507,5510,5513,5517,5520,5523,5526,5531,5534],[11,5234,5235],{},"Start a useful AI agent workflow with an operational problem and a result someone can use. “Research, write, review” leaves a lot undecided: what the writer can rely on, what the review must establish, and what happens when the sources cannot answer the brief.",[11,5237,5238],{},"Work backward from that result. Define the evidence it needs, the decisions that lead to it, and who owns those decisions. Then give each agent the part it can actually carry out.",[23,5240,5242],{"id":5241},"give-the-workflow-a-job-with-an-endpoint","Give the workflow a job with an endpoint",[11,5244,5245],{},"Consider a hypothetical request: prepare an article explaining a proposed support-triage process. The reader is a support lead deciding whether the proposal fits their team. They need to understand who suggests a ticket category, who makes the decision, and what happens next.",[11,5247,5248],{},"Our workflow produces the article; the support-triage process is the subject it explains.",[11,5250,5251],{},"The finished result is a reviewed article packet: the canonical text, its supporting sources, and the review decisions for that version. Publication sits outside this example. Nobody needs access to a live support queue to write the explanation.",[23,5253,5255],{"id":5254},"work-backward-into-a-small-plan","Work backward into a small plan",[11,5257,5258],{},"A reviewed packet depends on an accepted candidate and its reviews. Work backward again: reviewers need the draft and its sources, and the writer needs a brief those sources can support.",[11,5260,5261,5262,5265],{},"For this job, use one coordinating agent, a writer, and independent reviewers. The coordinator owns progression and the final result; specialists return bounded work. The distinction between an ",[15,5263,5264],{"href":5144},"agent, workflow, and orchestrator"," helps keep those responsibilities clear.",[11,5267,5268],{},"The resulting plan is small enough to inspect:",[928,5270,5271,5284],{},[931,5272,5273],{},[934,5274,5275,5278,5281],{},[937,5276,5277],{},"Stage and owner",[937,5279,5280],{},"What must be available",[937,5282,5283],{},"Return that permits the next stage",[947,5285,5286,5297,5308,5319,5330],{},[934,5287,5288,5291,5294],{},[952,5289,5290],{},"Scope and sources — coordinator",[952,5292,5293],{},"The brief, source note, voice guidance, and action boundary",[952,5295,5296],{},"Accepted scope, usable source references, and no missing fact essential to the brief",[934,5298,5299,5302,5305],{},[952,5300,5301],{},"Draft — writer",[952,5303,5304],{},"Those accepted inputs",[952,5306,5307],{},"Article candidate and a map from material claims to sources; any unresolved questions remain explicit",[934,5309,5310,5313,5316],{},[952,5311,5312],{},"Review — independent reviewers",[952,5314,5315],{},"The exact candidate and the same accepted inputs",[952,5317,5318],{},"Findings tied to passages, requirements, and evidence, covering claims, voice, and disclosure",[934,5320,5321,5324,5327],{},[952,5322,5323],{},"Resolve findings — coordinator and writer",[952,5325,5326],{},"Reviews for that candidate",[952,5328,5329],{},"Decisions on the findings, bounded repairs where needed, and review of the affected text",[934,5331,5332,5335,5338],{},[952,5333,5334],{},"Return the packet — coordinator",[952,5336,5337],{},"The current candidate and completed checks",[952,5339,5340],{},"A ready packet if acceptance is met; otherwise a blocked return with the unfinished condition and recovery information",[11,5342,5343,5344,5346],{},"StackOS's workflow authoring guidance starts with this same design order: the problem, useful outcome, operator path, and agent path. A reusable ",[15,5345,5175],{"href":5174}," needs those decisions even when its individual steps involve judgment.",[23,5348,5350],{"id":5349},"supply-the-inputs-and-acceptance-criteria","Supply the inputs and acceptance criteria",[11,5352,5353],{},"Here are the inputs for the exercise. The names are illustrative references; replace them with accessible files or records in your own workflow.",[928,5355,5356,5366],{},[931,5357,5358],{},[934,5359,5360,5363],{},[937,5361,5362],{},"Input",[937,5364,5365],{},"What it contains",[947,5367,5368,5378,5388],{},[934,5369,5370,5375],{},[952,5371,5372],{},[66,5373,5374],{},"brief-v1",[952,5376,5377],{},"Explain the proposed process to support leads, including who decides and where the process stops. Include one clearly invented ticket example. Return the reviewed article packet.",[934,5379,5380,5385],{},[952,5381,5382],{},[66,5383,5384],{},"process-notes-v1",[952,5386,5387],{},"The invented source note below, approved for use in the exercise. It describes a proposal, with no trial results.",[934,5389,5390,5395],{},[952,5391,5392],{},[66,5393,5394],{},"voice-v1",[952,5396,5397],{},"Use plain language, explain unfamiliar terms, and write for a peer considering the proposal. Exclude private customer details.",[11,5399,5400],{},"The source note says:",[42,5402,5403],{},[11,5404,5405],{},"A support operator supplies a ticket's text. An agent suggests a category and gives its reason. The support lead accepts or corrects the suggestion. This process ends with the lead's decision; it does not send a customer reply or change the live queue.",[11,5407,5408],{},"That is enough to explain this small proposal. It gives the writer no basis for claims about faster replies, better decisions, or results from a real team.",[11,5410,5411],{},"Before assigning work, write down what acceptance requires:",[228,5413,5414,5417,5420,5423],{},[141,5415,5416],{},"The article explains the proposed steps and the lead's decision, with an invented example a reader can follow.",[141,5418,5419],{},"Material statements about the proposal match the supplied note. The source record identifies what supports them.",[141,5421,5422],{},"Independent review checks the claims, the requested voice, and public-use boundaries. Findings that prevent acceptance are resolved in the final text.",[141,5424,5425],{},"The returned packet identifies the exact article version and its reviews, and the next person can retrieve them.",[11,5427,5428],{},"These conditions also give the operator a clear role. They supply the brief, source material, audience, and authority. If the source omits a decision essential to the explanation, the workflow returns that specific gap to them. Ordinary drafting and repair can proceed within the authority already supplied.",[23,5430,5432],{"id":5431},"give-each-step-enough-to-act-on","Give each step enough to act on",[11,5434,5435],{},"The writer's assignment can now be direct:",[42,5437,5438],{},[11,5439,5440,5441,807,5443,3919,5445,5447],{},"Use ",[66,5442,5374],{},[66,5444,5384],{},[66,5446,5394],{}," to write the explanatory article. Show how an invented ticket moves from the operator's supplied text to the lead's category decision. Keep the proposal's limits visible. Return the draft and its claim-to-source map to the coordinator. If a required process detail is missing, identify the gap instead of inventing it.",[11,5449,5450],{},"Provide the writer with read access to those inputs and a place to write its candidate. Reviewers need the same inputs and candidate, plus a place to return findings. Keep source records unchanged during drafting, and leave publishing and live support operations outside these tool grants.",[11,5452,5453],{},"Give the claim reviewer a specific question: does the article accurately explain the proposal in the supplied note? The voice reviewer checks whether a support lead can follow it in the agreed register. The disclosure reviewer checks the public-use boundary, including whether the example contains private details. Each returns evidence for its judgment to the coordinator.",[11,5455,5456,5457,5459],{},"This is the local ",[15,5458,5224],{"href":4930},": the receiver can find its inputs, perform the assigned work, and return something the next person can use. A role name such as “editor” would leave most of that assignment unstated.",[23,5461,5463],{"id":5462},"decide-how-review-can-end","Decide how review can end",[11,5465,5466],{},"For this example, allow up to two repair rounds after the first review. Each round addresses the findings the coordinator has accepted and includes the checks affected by those changes. Two is a limit chosen for this exercise; change it deliberately for another job.",[11,5468,5469,5470,5472],{},"The coordinator should evaluate ",[15,5471,4123],{"href":4122}," before sending the article back. A request for a different introduction needs a reason grounded in the brief or voice guidance. It should not keep reopening a usable article just because another opening is possible.",[11,5474,5475],{},"Suppose the writer adds an unsupported claim about faster replies. Removing it can be a sufficient repair: the brief asks for an explanation of the proposal, and that explanation remains useful without a performance promise. The reviewer still needs to check the revised paragraph for any remaining implication of measured results.",[11,5477,5478],{},"A missing decision owner is different. If the source note said only that the agent suggests a category, the writer could not explain who accepts or corrects it. Removing that part of the article would leave the brief unanswered. Return the gap to the operator: who makes the final category decision, and where is that decision recorded in the proposal?",[11,5480,5481],{},"There are two possible returns:",[11,5483,5484,5487],{},[31,5485,5486],{},"Ready:"," the candidate meets the acceptance conditions defined above. Return that exact text with its sources and review decisions.",[11,5489,5490,5493],{},[31,5491,5492],{},"Blocked:"," an essential fact remains unavailable, or an acceptance condition is still unmet when the repair limit is reached. Preserve the latest candidate, attempted repairs, evidence, unresolved condition, and the person or agent who can resolve it. State the smallest missing input or decision.",[11,5495,5496],{},"A review limit stops the work from looping. It does not turn the remaining defect into an acceptable result.",[23,5498,5500],{"id":5499},"save-enough-state-to-continue","Save enough state to continue",[11,5502,5503],{},"Conversation context is useful working memory. It is a poor system of record.",[11,5505,5506],{},"Keep the original brief and authority, source versions, current candidate, accepted outputs, review decisions, and open work in the project's durable records. Link the article to that record so someone returning later can find the evidence behind its status.",[11,5508,5509],{},"Imagine the run pauses after review, before repair. The next coordinator should be able to retrieve the reviewed candidate, see which findings were accepted, and assign the outstanding changes. A newer file needs comparison with that record before the old review can be relied on. Otherwise “reviewed” may describe text that is no longer there.",[11,5511,5512],{},"The operator should be able to inspect the same state: the article is in repair, these findings remain, and this is what would make it ready. They should not have to reconstruct it from a conversation between agents.",[23,5514,5516],{"id":5515},"try-it-without-filling-in-the-blanks-yourself","Try it without filling in the blanks yourself",[11,5518,5519],{},"A design can look complete while its author is quietly supplying the missing context. Give a fresh agent the brief and the three exercise inputs, with access to the workflow instructions and permitted tools. Ask it to carry out the article-preparation job without additional design hints.",[11,5521,5522],{},"With the complete source note, it should first check that the material covers the brief, then produce the defined packet. Inspect its article, example, source map and candidate-bound reviews against the acceptance criteria; a “complete” label is only a claim about the result.",[11,5524,5525],{},"Then repeat with a source note that omits the decision owner:",[42,5527,5528],{},[11,5529,5530],{},"A support operator supplies a ticket's text. An agent suggests a category and gives its reason. The proposal excludes customer replies and live queue changes.",[11,5532,5533],{},"The expected return is a specific block: the proposal does not establish who accepts or corrects the category, so the article cannot yet explain that part. The saved record should identify the missing source detail and where work can resume when it arrives.",[11,5535,5536],{},"Record what the fresh agent did first, what it returned, and where it needed an extra hint. Those observations tell you which part of this design still depends on information you have not given it.",{"title":326,"searchDepth":327,"depth":327,"links":5538},[5539,5540,5541,5542,5543,5544,5545],{"id":5241,"depth":327,"text":5242},{"id":5254,"depth":327,"text":5255},{"id":5349,"depth":327,"text":5350},{"id":5431,"depth":327,"text":5432},{"id":5462,"depth":327,"text":5463},{"id":5499,"depth":327,"text":5500},{"id":5515,"depth":327,"text":5516},"Design an AI agent workflow around a useful result. Follow one article-preparation example through inputs, dependencies, review, recovery, and a clear stopping point.",{},"\u002Farticles\u002Fhow-to-build-ai-agent-workflow",[5550,345,587],"stackos-workflow-workflow-author",[5217,2811,2810],[353,2500],"Learn how to build an AI agent workflow from the problem and outcome backward",{"title":5230,"description":5546},"articles\u002Fhow-to-build-ai-agent-workflow",[4764,4172,4171],"8nF-154dQlgfAdSmcLYQhs0DNynFGgTQjvQMouF6MVc",{"id":5559,"title":5560,"author":6,"body":5561,"category":581,"description":5780,"extension":336,"featured":340,"heroImage":338,"meta":5781,"navigation":340,"path":5782,"publishedAt":5783,"readingTime":2492,"relatedAgents":5784,"relatedArticles":5785,"relatedWorkflows":5786,"searchIntent":5787,"seo":5788,"stem":5789,"topics":5790,"updatedAt":4162,"visual":3549,"__hash__":5793},"articles\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator.md","AI agent vs. workflow vs. orchestrator: what is the difference?",{"type":8,"value":5562,"toc":5771},[5563,5566,5569,5574,5624,5628,5631,5634,5645,5648,5651,5655,5658,5661,5664,5667,5671,5674,5677,5680,5684,5687,5704,5707,5711,5714,5717,5720,5723,5727,5730,5733,5737,5740,5757,5760],[11,5564,5565],{},"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,5567,5568],{},"The distinction is less about names than ownership. When ownership blurs, agents reconstruct state, workflows become long prompts, and orchestrators accept every plausible suggestion.",[5570,5571],"article-concept-visual",{"caption":5572,"mode":3549,"title":5573},"The workflow holds the contract. Agents handle bounded responsibilities. The orchestrator decides how the complete job should move.","One job, three different owners",[928,5575,5576,5589],{},[931,5577,5578],{},[934,5579,5580,5583,5586],{},[937,5581,5582],{},"Component",[937,5584,5585],{},"What it owns",[937,5587,5588],{},"What it should not own",[947,5590,5591,5602,5613],{},[934,5592,5593,5596,5599],{},[952,5594,5595],{},"Agent",[952,5597,5598],{},"One bounded judgment, transformation, review, or execution responsibility",[952,5600,5601],{},"Quietly redefining the accepted plan",[934,5603,5604,5607,5610],{},[952,5605,5606],{},"Workflow",[952,5608,5609],{},"State, dependencies, tool boundaries, expected outputs, acceptance criteria, and recovery paths",[952,5611,5612],{},"Deciding every exception at runtime",[934,5614,5615,5618,5621],{},[952,5616,5617],{},"Orchestrator",[952,5619,5620],{},"Next-step reasoning, context assembly, delegation, feedback triage, and recovery",[952,5622,5623],{},"Performing every specialist task or accepting every reviewer idea",[23,5625,5627],{"id":5626},"what-is-an-ai-agent","What is an AI agent?",[11,5629,5630],{},"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,5632,5633],{},"The work can call for different kinds of agents:",[228,5635,5636,5639,5642],{},[141,5637,5638],{},"A reasoning agent makes a bounded judgment and explains why.",[141,5640,5641],{},"A mechanical agent performs a defined transformation or handoff without taking over strategy.",[141,5643,5644],{},"A review agent challenges another result and returns findings for adjudication.",[11,5646,5647],{},"These roles can use the same underlying model. The important separation is responsibility, not model count.",[11,5649,5650],{},"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.",[23,5652,5654],{"id":5653},"what-is-a-workflow","What is a workflow?",[11,5656,5657],{},"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,5659,5660],{},"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,5662,5663],{},"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,5665,5666],{},"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.",[23,5668,5670],{"id":5669},"what-is-an-orchestrator","What is an orchestrator?",[11,5672,5673],{},"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,5675,5676],{},"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,5678,5679],{},"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.",[23,5681,5683],{"id":5682},"how-do-they-work-together","How do they work together?",[11,5685,5686],{},"Take an article production job:",[138,5688,5689,5692,5695,5698,5701],{},[141,5690,5691],{},"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.",[141,5693,5694],{},"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.",[141,5696,5697],{},"Specialist agents collect evidence, draft the article, review claims, and check disclosure within their assigned boundaries.",[141,5699,5700],{},"Review findings return to the orchestrator. It decides which findings require repair and which are preferences or scope drift.",[141,5702,5703],{},"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,5705,5706],{},"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.",[23,5708,5710],{"id":5709},"what-did-we-learn-from-refining-real-workflows","What did we learn from refining real workflows?",[11,5712,5713],{},"Two failures made the distinction concrete for us.",[11,5715,5716],{},"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,5718,5719],{},"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,5721,5722],{},"Both failures involved capable agents. The missing pieces were workflow state and orchestrator judgment.",[23,5724,5726],{"id":5725},"do-you-need-multiple-models","Do you need multiple models?",[11,5728,5729],{},"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,5731,5732],{},"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.",[23,5734,5736],{"id":5735},"which-part-should-you-design-first","Which part should you design first?",[11,5738,5739],{},"Use this order:",[138,5741,5742,5745,5748,5751,5754],{},[141,5743,5744],{},"Define the problem, useful outcome, side-effect boundary, and terminal condition.",[141,5746,5747],{},"Build the workflow around the state, dependencies, authority, evidence, and recovery the job needs.",[141,5749,5750],{},"Define what the orchestrator must reason about: next steps, exceptions, feedback, drift, and closeout.",[141,5752,5753],{},"Add an agent only when a bounded responsibility deserves its own context and output contract.",[141,5755,5756],{},"Give the workflow to a fresh agent, observe the work, and ask where it had to guess, investigate, or make an undocumented decision.",[11,5758,5759],{},"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,5761,5762,5763,5767,5768,190],{},"For the adjacent concepts, see ",[15,5764,5766],{"href":5765},"\u002Flibrary\u002Farticles\u002Fwhat-is-an-agentic-workflow","what makes a workflow agentic"," and the practical guide to ",[15,5769,5224],{"href":5770},"\u002Flibrary\u002Farticles\u002Fai-agent-experience",{"title":326,"searchDepth":327,"depth":327,"links":5772},[5773,5774,5775,5776,5777,5778,5779],{"id":5626,"depth":327,"text":5627},{"id":5653,"depth":327,"text":5654},{"id":5669,"depth":327,"text":5670},{"id":5682,"depth":327,"text":5683},{"id":5709,"depth":327,"text":5710},{"id":5725,"depth":327,"text":5726},{"id":5735,"depth":327,"text":5736},"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",[347,587],[2811,850],[353,2500],"Compare AI agents, workflows, and orchestrators in plain language",{"title":5560,"description":5780},"articles\u002Fai-agent-vs-workflow-vs-orchestrator",[5791,5792,2819],"AI agents","orchestrators","5dbHMEnUQm_EksylaO0-_-Uc38_NGPKp4CHwoHL24hA",{"id":5795,"title":5796,"author":6,"body":5797,"category":5986,"description":5987,"extension":336,"featured":337,"heroImage":338,"meta":5988,"navigation":340,"path":5989,"publishedAt":5783,"readingTime":2807,"relatedAgents":5990,"relatedArticles":5991,"relatedWorkflows":5992,"searchIntent":5993,"seo":5994,"stem":5995,"topics":5996,"updatedAt":361,"visual":362,"__hash__":6000},"articles\u002Farticles\u002Fhow-ai-agents-use-accounts-safely.md","How can AI agents use business accounts without seeing the login?",{"type":8,"value":5798,"toc":5978},[5799,5802,5805,5808,5812,5821,5824,5827,5830,5834,5837,5840,5860,5863,5866,5884,5898,5901,5905,5908,5911,5915,5930,5934,5937,5975],[11,5800,5801],{},"An AI agent can use a business account through an action runtime that holds the credential. The agent receives an account reference and requests a particular operation. The runtime checks the request, uses the credential, and returns the result.",[11,5803,5804],{},"In StackOS, that runtime is the local daemon. Shared authentication code resolves the credential, and the provider connector uses it to carry out the action. Both handle credential material inside the daemon; the agent-facing interface supplies safe references and account information.",[11,5806,5807],{},"Keeping the login there answers one question. The next is which actions this agent is allowed to request through that account.",[23,5809,5811],{"id":5810},"a-stored-account-and-a-projects-connection-have-different-jobs","A stored account and a project's connection have different jobs",[11,5813,5171,5814,5817,5818,5820],{},[31,5815,5816],{},"Account"," is the reusable identity StackOS stores for a provider. A ",[31,5819,433],{}," attaches that Account to a particular project. The attachment does not make another copy of its credential.",[11,5822,5823],{},"The agent can receive the provider and account name, authentication method, saved connection status, known scopes, and an opaque credential reference. That reference lets StackOS find the credential for an authorized action. It is not the password or token itself.",[11,5825,5826],{},"Credentials belong in account setup. Putting them in a prompt, project resource, workflow file, or article would create another place that can be copied or shared. The agent only needs enough information to select the intended account and action.",[11,5828,5829],{},"A connection marked ready tells the agent about its saved setup. Access to a particular provider endpoint or property still depends on the credential's permissions. A successful account test does not establish every permission the next task might need.",[23,5831,5833],{"id":5832},"a-report-step-cannot-borrow-the-accounts-permission-to-write","A report step cannot borrow the account's permission to write",[11,5835,5836],{},"Consider a hypothetical Search Console workflow. An operator connects a Google Account and attaches it to a project. The active step may read Search Analytics for an authorized website property. Its grant excludes sitemap submission, even if the Google Account has permission to submit one.",[11,5838,5839],{},"The agent requests the report with the property and date range, using the safe account reference. Several separate checks matter:",[228,5841,5842,5848,5854],{},[141,5843,5844,5847],{},[31,5845,5846],{},"Project attachment:"," this project must be allowed to use that Account.",[141,5849,5850,5853],{},[31,5851,5852],{},"Step authority:"," the running workflow step must name and permit the report action.",[141,5855,5856,5859],{},[31,5857,5858],{},"Provider access:"," the credential must have the required scope, and Google must permit access to the requested property.",[11,5861,5862],{},"StackOS validates the named action and its inputs, checks the workflow authority, and resolves usable credentials inside the daemon before the connector performs the business request. Google applies its own permissions to that request.",[11,5864,5865],{},"Now suppose the same reporting step asks to submit a sitemap. Its action grant does not allow that operation, so StackOS rejects the request before dispatching the sitemap action. The agent should report the missing authority. It should not broaden the step's grant just because the connected Account could perform the write.",[11,5867,5868,5869,5874,5875,5878,5879,5883],{},"An authorized submission step would also need the Account's sitemap write access, the required Google OAuth scope, and permission for the property. Google's ",[15,5870,5873],{"href":5871,"rel":5872},"https:\u002F\u002Fdevelopers.google.com\u002Fwebmaster-tools\u002Fv1\u002Fsitemaps\u002Fsubmit",[19],"sitemap submission endpoint"," requires the ",[66,5876,5877],{},"webmasters"," scope and registers a sitemap URL; it does not edit the sitemap file. Google treats ",[15,5880,5882],{"href":93,"rel":5881},[19],"sitemap submission as a hint",", with no guarantee that it will download or crawl it.",[11,5885,5886,5887,5892,5893,5897],{},"This is a practical application of ",[15,5888,5891],{"href":5889,"rel":5890},"https:\u002F\u002Fcsrc.nist.gov\u002Fglossary\u002Fterm\u002Fleast_privilege",[19],"NIST's least-privilege principle",": give a process the resources and authority needed for its task. The reporting step can use the account for its assigned read while remaining unable to submit the sitemap. The ",[15,5894,5896],{"href":5895},"\u002Flibrary\u002Fworkflows\u002F","workflow library"," shows the broader jobs in which these action boundaries sit.",[11,5899,5900],{},"One-off writes outside a workflow have their own execution contract. The caller must explicitly confirm the action and state its intent; dry runs are exempt. Authority already supplied by the operator can satisfy that contract without asking the person to approve the same action again.",[23,5902,5904],{"id":5903},"what-comes-back-from-the-action","What comes back from the action",[11,5906,5907],{},"A permitted action can return private business data. Keeping the credential out of the response does not make that data public. The agent still needs to follow the project's rules for who may receive the report and which details may be shared.",[11,5909,5910],{},"Execution receipts help inspect what was requested and what result was returned. For an action that changes an external system, an error after the request may leave its effect uncertain. Check the provider's state or request status before deciding whether to repeat it. Idempotency provides retry protection, but it is not a universal guarantee that every provider will apply an operation exactly once.",[1508,5912,5914],{"id":5913},"when-the-connection-uses-mcp","When the connection uses MCP",[11,5916,5917,5918,5923,5924,5929],{},"The authorization boundary also matters when an agent connects to a remote tool server. The ",[15,5919,5922],{"href":5920,"rel":5921},"https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2026-07-28\u002Fbasic\u002Fauthorization",[19],"MCP authorization specification"," describes its HTTP flow with scopes for the intended operations and tokens bound to the intended MCP server. Stdio connections are treated differently. The official ",[15,5925,5928],{"href":5926,"rel":5927},"https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002F2026-07-28\u002Ftutorials\u002Fsecurity\u002Fsecurity_best_practices",[19],"MCP security guidance"," prohibits token passthrough: a server accepting a token without checking that it was intended for that server, then forwarding it to a downstream API.",[23,5931,5933],{"id":5932},"choose-which-access-you-want-to-remove","Choose which access you want to remove",[11,5935,5936],{},"“Disconnect the account” can mean removing one project's access, deleting the credential from StackOS, or invalidating it at Google. Choose the operation that matches the intended effect.",[928,5938,5939,5949],{},[931,5940,5941],{},[934,5942,5943,5946],{},[937,5944,5945],{},"What you want to do",[937,5947,5948],{},"Operation and effect",[947,5950,5951,5959,5967],{},[934,5952,5953,5956],{},[952,5954,5955],{},"Stop this project using the Account",[952,5957,5958],{},"Detach its Connection. The reusable Account and attachments to other projects remain. Running work and enabled communication profiles can still depend on this Account. You may need to assign them another Account or disable them before detaching.",[934,5960,5961,5964],{},[952,5962,5963],{},"Remove the credential stored by StackOS",[952,5965,5966],{},"Detach the Account from every project, then revoke it locally. StackOS removes the encrypted credential backing and retains a non-executable audit record.",[934,5968,5969,5972],{},[952,5970,5971],{},"Revoke or rotate the credential at its provider",[952,5973,5974],{},"Use the provider's controls or an explicitly supported provider operation. Local account removal does not generally invalidate the credential at the provider.",[11,5976,5977],{},"Removing access does not undo completed actions or guarantee that every request already in flight is cancelled. For the Search Console example, detaching the reporting project's Connection leaves the Account available to other attached projects. If the goal is to invalidate the Google credential itself, use Google's revocation or rotation controls and check that result separately.",{"title":326,"searchDepth":327,"depth":327,"links":5979},[5980,5981,5982,5985],{"id":5810,"depth":327,"text":5811},{"id":5832,"depth":327,"text":5833},{"id":5903,"depth":327,"text":5904,"children":5983},[5984],{"id":5913,"depth":1589,"text":5914},{"id":5932,"depth":327,"text":5933},"Security","See how StackOS keeps credentials in its runtime, checks a Search Console action against separate permissions, and distinguishes three ways to remove account access.",{},"\u002Farticles\u002Fhow-ai-agents-use-accounts-safely",[3349],[850,2811],[2500,353],"Understand how AI agents can use connected accounts without receiving credentials",{"title":5796,"description":5987},"articles\u002Fhow-ai-agents-use-accounts-safely",[5997,5998,5999],"AI agent security","credentials","local software","-dxYkVilMB-KyptHkYr43uiNs74noS2XiS61kRZ0N4c",{"id":6002,"title":6003,"author":6,"body":6004,"category":6154,"description":6155,"extension":336,"featured":340,"heroImage":338,"meta":6156,"navigation":340,"path":6157,"publishedAt":5783,"readingTime":585,"relatedAgents":6158,"relatedArticles":6159,"relatedWorkflows":6160,"searchIntent":6162,"seo":6163,"stem":6164,"topics":6165,"updatedAt":6169,"visual":6041,"__hash__":6170},"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":6005,"toc":6147},[6006,6009,6012,6020,6024,6027,6030,6038,6043,6047,6054,6057,6061,6068,6074,6077,6080,6087,6093,6097,6100,6106,6109,6113],[11,6007,6008],{},"You ask your AI client to look at search traffic for your website. Before it reads a row, it needs to know which project you mean, which account it can use, and which Search Console property to query.",[11,6010,6011],{},"You can do that from Codex, Claude Code, or Gemini CLI. Connect the client to StackOS through MCP so it can call StackOS tools. Then connect Google Search Console to the project and ask for a report you can check.",[11,6013,6014,6015,6019],{},"Start with the ",[15,6016,6018],{"href":6017},"\u002Fgetting-started\u002F","getting-started guide"," for installation and client setup. The walkthrough below uses one read-only report to check the connection, save a useful result, and pick up the work in another client.",[23,6021,6023],{"id":6022},"connect-the-client-to-the-right-project","Connect the client to the right project",[11,6025,6026],{},"StackOS install and repair register its local MCP bridge with supported clients found on your Mac. Each client keeps its own settings and needs a fresh session after registration.",[11,6028,6029],{},"Open Codex CLI, Claude Code, or Gemini CLI from the real folder for the site you want to work on. Ask it to use StackOS and confirm the project name and project link. StackOS uses the folder's project binding; it does not choose whichever project someone used last. If you use a client without a project folder, such as Claude Desktop, explicitly select the intended project.",[11,6031,6032,6033,6037],{},"The AI chooses the next step. StackOS stores the plan, scopes the tool call, and records what happened. Provider credentials stay inside the StackOS daemon; the client receives safe references and action results. The ",[15,6034,6036],{"href":6035},"\u002Flibrary\u002Farticles\u002Fhow-ai-agents-use-accounts-safely\u002F","account-access guide"," explains that boundary in detail.",[5570,6039],{"caption":6040,"mode":6041,"title":6042},"Each supported client can reach the same durable project state and the tools available to complete the work.","connections","Keep the AI client. Keep the apps.",[23,6044,6046],{"id":6045},"confirm-access-to-your-search-console-property","Confirm access to your Search Console property",[11,6048,6049,6050,6053],{},"Open the project's Connections page and add Google Search Console if it is missing. Follow the ",[15,6051,6052],{"href":1907},"Search Console integration guide"," for provider setup and permissions. Keep credentials in StackOS.",[11,6055,6056],{},"A connected Google account still needs access to the particular Search Console property. Ask the agent to list the properties it can read, then use the exact property identifier from that result.",[23,6058,6060],{"id":6059},"ask-for-one-dated-report","Ask for one dated report",[11,6062,6063,6064,6067],{},"Replace ",[66,6065,6066],{},"[SEARCH_CONSOLE_PROPERTY]"," with your property. The dates below are an example of a completed reporting period; replace them with the dates you want to inspect.",[689,6069,6072],{"className":6070,"code":6071,"language":694,"meta":326},[692],"Use StackOS for this project. Confirm the project name and that you can\nread the Search Console property [SEARCH_CONSOLE_PROPERTY].\n\nRead web search performance from 2026-08-29 through 2026-09-25, inclusive,\nusing final data. Show the top 10 pages by clicks with clicks, impressions,\nCTR, and average position.\n\nChoose one existing page from that table for a closer look. Say why you\nselected it, then show the queries returned for that exact page using\nthe same dates, search type, and data state. Explain any missing data\nor limits that affect the interpretation.\n\nSave the report, its source references, and one proposed next step in\nthis StackOS project. Give me the saved report or task reference.\nKeep this read-only: do not edit the site or submit anything to Google.\n",[66,6073,6071],{"__ignoreMap":326},[11,6075,6076],{},"The report should name the property, dates, search type, and data state, then show the page table and the selected page's query table. You should also have a reference you can use to retrieve the report later.",[11,6078,6079],{},"Check that the selected page belongs to the site you intended. Read it alongside the returned queries, then decide whether the proposed next step would help answer those searches.",[11,6081,4030,6082,6086],{},[15,6083,6085],{"href":1856,"rel":6084},[19],"Search Analytics API"," returns top rows and doesn't guarantee every row. Some queries are omitted. An absent query is not evidence of zero traffic, and a page with only a few impressions gives little basis for deciding what to change.",[11,6088,6089,6090,6092],{},"If the report supports an edit, the ",[15,6091,5896],{"href":5895}," includes content refresh and website analysis. Ask the agent to choose the appropriate workflow and carry the report's source references into that work. Reading a report does not itself start an editing or publishing workflow.",[23,6094,6096],{"id":6095},"continue-from-the-saved-result","Continue from the saved result",[11,6098,6099],{},"On the same Mac, open another supported client with its own working StackOS connection. Use the same project folder, confirm the project, and give it the reference returned by the first client:",[689,6101,6104],{"className":6102,"code":6103,"language":694,"meta":326},[692],"Use the same StackOS project for this workspace. Read the saved report\nor task at [SAVED_REPORT_OR_TASK_REF]. Confirm its property and reporting\ndates, summarize what was completed and what remains, and show me the\nproposed next step before making changes.\n",[66,6105,6103],{"__ignoreMap":326},[11,6107,6108],{},"StackOS keeps the project records the agent saved: reports and evidence, plans and completed steps, decisions, and action history. Private chat transcripts and unsaved conversation context don't transfer between clients. Include any extra instruction or decision that was left only in the previous chat.",[23,6110,6112],{"id":6111},"if-the-result-is-missing-or-wrong","If the result is missing or wrong",[228,6114,6115,6123,6129,6135,6141],{},[141,6116,6117,6120,6121,190],{},[31,6118,6119],{},"The client cannot see StackOS."," Start a fresh client session. If registration is missing, use the repair steps in the ",[15,6122,6018],{"href":6017},[141,6124,6125,6128],{},[31,6126,6127],{},"The project is wrong."," Reopen the client from the correct folder or explicitly select the intended project before continuing.",[141,6130,6131,6134],{},[31,6132,6133],{},"The property is missing or access is denied."," Check the exact property and the connected account's Search Console permissions. Reconnecting the same account won't grant it access to a property it cannot read.",[141,6136,6137,6140],{},[31,6138,6139],{},"The report has no rows."," Check the property, dates, search type, and filters before interpreting the result. Ask the agent to distinguish an empty response from a failed request.",[141,6142,6143,6146],{},[31,6144,6145],{},"The next client cannot find the work."," Confirm the project and saved reference. If the result existed only in chat, return to that session and have the agent save the report and any decisions needed to continue.",{"title":326,"searchDepth":327,"depth":327,"links":6148},[6149,6150,6151,6152,6153],{"id":6022,"depth":327,"text":6023},{"id":6045,"depth":327,"text":6046},{"id":6059,"depth":327,"text":6060},{"id":6095,"depth":327,"text":6096},{"id":6111,"depth":327,"text":6112},"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",[],[2811,3839],[6161,2500],"communications-customer-feedback-intake","Learn how to connect an existing AI client to existing business tools",{"title":6003,"description":6155},"articles\u002Fuse-codex-claude-gemini-with-existing-tools",[682,709,6166,6167,6168],"Gemini CLI","MCP","AI tools","2026-09-29","kj4RkcwEekMFOCq-zhdcKpa9xFZPIpMgxM0OkwjtTtI",{"id":6172,"title":6173,"author":6,"body":6174,"category":6461,"description":6462,"extension":336,"featured":340,"heroImage":338,"meta":6463,"navigation":340,"path":6464,"publishedAt":5783,"readingTime":2492,"relatedAgents":6465,"relatedArticles":6466,"relatedWorkflows":6467,"searchIntent":6469,"seo":6470,"stem":6471,"topics":6472,"updatedAt":6169,"visual":4768,"__hash__":6474},"articles\u002Farticles\u002Fwhat-is-an-agentic-workflow.md","What is an agentic workflow? A practical guide to AI-powered work",{"type":8,"value":6175,"toc":6449},[6176,6179,6182,6185,6189,6193,6196,6199,6213,6216,6220,6223,6261,6264,6268,6271,6276,6279,6283,6291,6294,6297,6300,6303,6307,6310,6313,6316,6320,6323,6326,6330,6392,6395,6403,6407,6410,6427,6430,6439,6443,6446],[11,6177,6178],{},"An agentic workflow lets AI choose the next action as it works toward a goal. A source may contradict the brief, or a reviewer may find a claim the draft cannot support. The agent has to decide how to continue.",[11,6180,6181],{},"It might read another source, change the proposed angle, repair the draft, or stop because the requested result is ready. The useful distinction is that the decision depends on what the agent finds during the work.",[11,6183,6184],{},"In StackOS, that judgment sits inside a saved plan with scoped tools, evidence, checks, and a definition of done. The agent makes decisions; StackOS stores the state, validates tool calls, and records their results.",[6186,6187],"article-workflow-visual",{"title":6188,"workflow":353},"A complete content workflow, from request to verified result",[23,6190,6192],{"id":6191},"what-makes-a-workflow-agentic","What makes a workflow agentic?",[11,6194,6195],{},"Fixed automation follows a known mapping: when this happens, do that. Agent judgment is useful when the next action depends on meaning, evidence, or a changing situation.",[11,6197,6198],{},"Consider four decisions from a content workflow:",[228,6200,6201,6204,6207,6210],{},[141,6202,6203],{},"Is an operator interview needed, or is the relevant experience already captured?",[141,6205,6206],{},"Does the evidence support the proposed angle?",[141,6208,6209],{},"Does a reviewer finding require a correction, or does it expand the assignment?",[141,6211,6212],{},"Does the finished article answer the request, or is a material claim still unresolved?",[11,6214,6215],{},"The workflow gives those decisions boundaries: the allowed actions, expected outputs, and stopping rule. A person needs to step in when a material choice, permission, or piece of context is missing. Routine decisions can stay with the agent responsible for the work.",[23,6217,6219],{"id":6218},"what-should-the-workflow-contain","What should the workflow contain?",[11,6221,6222],{},"The practical model used in StackOS covers six things:",[138,6224,6225,6231,6237,6243,6249,6255],{},[141,6226,6227,6230],{},[31,6228,6229],{},"Problem and outcome."," Name the failure, friction, or decision AI should help with, the useful result, and which external changes are allowed.",[141,6232,6233,6236],{},[31,6234,6235],{},"State and dependencies."," Record what is pending, active, accepted, blocked, or complete, and which later work depends on it.",[141,6238,6239,6242],{},[31,6240,6241],{},"Context, tools, and authority."," Give each step the information and operations it needs without exposing unrelated history or broader access.",[141,6244,6245,6248],{},[31,6246,6247],{},"Decision ownership."," State what the coordinating agent decides and which bounded responsibilities belong to specialists, if the work needs them.",[141,6250,6251,6254],{},[31,6252,6253],{},"Outputs, evidence, and acceptance."," Define what each step must return, which claims need support, and how the result will be checked.",[141,6256,6257,6260],{},[31,6258,6259],{},"Recovery and a definition of done."," Describe how to continue after anticipated failures and what must be true before the job ends.",[11,6262,6263],{},"Stable rules can stay in the workflow, project records, and tool contracts. The agent needs the part of that context that affects its next decision.",[23,6265,6267],{"id":6266},"what-happens-from-request-to-result","What happens from request to result?",[11,6269,6270],{},"Consider this hypothetical content request:",[42,6272,6273],{},[11,6274,6275],{},"Write a practical article for editors deciding when to interview someone before drafting. Use the supplied notes, our approved voice guide, and the StackOS content-workflow documentation. Return a reviewed Markdown draft with its sources. Do not publish it.",[11,6277,6278],{},"One supplied note says, “Every article must start with an interview.” The agent needs to check that claim before building the article around it.",[1508,6280,6282],{"id":6281},"read-the-source-and-use-what-it-says","Read the source and use what it says",[11,6284,6285,6286,6290],{},"The coordinating agent selects the ",[15,6287,6289],{"href":6288},"\u002Flibrary\u002Fworkflows\u002Fbranding-content-production\u002F","content-production workflow"," and records the audience, sources, and requested output for this job. It asks a reading tool to retrieve that workflow's documentation and return the interview conditions.",[11,6292,6293],{},"A successful tool response is only the first check. The agent must confirm that the returned text belongs to the intended workflow and contains the relevant rule. An error message or unrelated page cannot support the note.",[11,6295,6296],{},"The workflow makes the interview conditional. Ask for missing firsthand context when the person's experience or judgment matters; an interview can be skipped when the existing material is sufficient. That contradicts the note's blanket instruction.",[11,6298,6299],{},"For this explanatory article, the documentation supplies the rule the editor needs. The agent records why an interview is unnecessary and chooses an angle about recognizing missing context. The writer can explain the difference between an article whose sources already answer the question and one that needs to establish what a person actually did or learned.",[11,6301,6302],{},"The source check has changed both the next step and the draft's advice. The agent skips the interview for a reason it can show, then writes from the supported rule.",[1508,6304,6306],{"id":6305},"review-the-advice-against-the-same-source","Review the advice against the same source",[11,6308,6309],{},"An independent claim reviewer receives the draft, its sources, and the original request. Suppose a later paragraph still tells editors to start every draft with an interview. The reviewer points to that sentence and the conditional rule it contradicts.",[11,6311,6312],{},"The coordinating agent checks the finding, sends the passage back for correction, and checks the revision. If the reviewer also suggests turning the article into a campaign, that suggestion does not expand this job. The request is for one reviewed draft.",[11,6314,6315],{},"Separate voice and disclosure reviews check whether the piece follows the approved guidance and whether its details are cleared for public use. The coordinating agent resolves the findings before accepting the final version.",[1508,6317,6319],{"id":6318},"resume-the-source-check-if-it-fails","Resume the source check if it fails",[11,6321,6322],{},"If the reading tool returns an error or the wrong page, the central claim stays unverified. The agent saves the source it tried to read, the failed result, and the work that depends on that check. Once the source is available or the input is corrected, it can resume the check and continue from the recorded state.",[11,6324,6325],{},"The job ends when the reviewed Markdown file, source references, and resolved findings are saved and retrievable. The coordinating agent opens the saved draft and checks it against the original request: it explains when an interview is useful, its material claims are supported, and no blocking review finding remains. The editor receives the draft reference. Publication is outside this request.",[23,6327,6329],{"id":6328},"how-is-this-different-from-a-chatbot-or-fixed-automation","How is this different from a chatbot or fixed automation?",[928,6331,6332,6348],{},[931,6333,6334],{},[934,6335,6336,6339,6342,6345],{},[937,6337,6338],{},"Mode",[937,6340,6341],{},"Best for",[937,6343,6344],{},"How it adapts",[937,6346,6347],{},"What marks completion",[947,6349,6350,6364,6378],{},[934,6351,6352,6355,6358,6361],{},[952,6353,6354],{},"Conversation",[952,6356,6357],{},"A question, explanation, or one-off draft",[952,6359,6360],{},"The model responds within the current context",[952,6362,6363],{},"A useful response is returned",[934,6365,6366,6369,6372,6375],{},[952,6367,6368],{},"Fixed automation",[952,6370,6371],{},"A stable trigger with a known action",[952,6373,6374],{},"Predetermined rules and branches",[952,6376,6377],{},"The configured action finishes",[934,6379,6380,6383,6386,6389],{},[952,6381,6382],{},"Agentic workflow",[952,6384,6385],{},"Multi-step work where evidence or state changes the next action",[952,6387,6388],{},"An agent evaluates results and chooses how to continue",[952,6390,6391],{},"The requested result meets its acceptance criteria",[11,6393,6394],{},"A conversation can call tools, and fixed automation can have many branches. In the content example, the consequential choice is what to do after a source contradicts the supplied note. The saved state carries that choice through writing and review.",[11,6396,6397,6398,6402],{},"Terminology varies. ",[15,6399,6401],{"href":2955,"rel":6400},[19],"Anthropic's guide to building agents"," distinguishes predefined workflows from agents that direct their own process and tool use, while grouping both as agentic systems. The definition here emphasizes adaptive judgment; the saved plan and review boundaries describe how StackOS organizes that work.",[23,6404,6406],{"id":6405},"where-can-agentic-workflows-be-used","Where can agentic workflows be used?",[11,6408,6409],{},"They are useful candidates when:",[228,6411,6412,6415,6418,6421,6424],{},[141,6413,6414],{},"the outcome spans several dependent stages or sessions;",[141,6416,6417],{},"the next step depends on evidence rather than a fixed rule;",[141,6419,6420],{},"different responsibilities need different context or independent review;",[141,6422,6423],{},"connected tools make external changes that need narrow permissions and recorded results;",[141,6425,6426],{},"failure needs recovery and continuation rather than a full restart.",[11,6428,6429],{},"For example, an engineering task may need another implementation pass after a test exposes a missed requirement. A support investigation may produce an answer or establish that a software fix is needed. A content task may need a different angle after its strongest proposed claim fails a source check. In each case, the result of one step changes the next decision.",[11,6431,6432,6433,6436,6437,190],{},"For the surrounding roles, see ",[15,6434,6435],{"href":5144},"AI agent vs. workflow vs. orchestrator",". For the context and tools each agent needs, see ",[15,6438,5224],{"href":4930},[23,6440,6442],{"id":6441},"when-should-you-use-one","When should you use one?",[11,6444,6445],{},"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,6447,6448],{},"Use a workflow when the work needs judgment and enough continuity to carry decisions, evidence, and unfinished work through to the result.",{"title":326,"searchDepth":327,"depth":327,"links":6450},[6451,6452,6453,6458,6459,6460],{"id":6191,"depth":327,"text":6192},{"id":6218,"depth":327,"text":6219},{"id":6266,"depth":327,"text":6267,"children":6454},[6455,6456,6457],{"id":6281,"depth":1589,"text":6282},{"id":6305,"depth":1589,"text":6306},{"id":6318,"depth":1589,"text":6319},{"id":6328,"depth":327,"text":6329},{"id":6405,"depth":327,"text":6406},{"id":6441,"depth":327,"text":6442},"Agentic workflows","An agentic workflow lets AI choose its next action from the evidence. Follow a content example through source checks, decisions, review, recovery, and a finished draft.",{},"\u002Farticles\u002Fwhat-is-an-agentic-workflow",[346,347],[5217,850],[2500,353,6468],"marketing-campaign-production","Understand what an agentic workflow is, how it works, and when to use one",{"title":6173,"description":6462},"articles\u002Fwhat-is-an-agentic-workflow",[2819,5791,6473],"workflow automation","RK6vS-fC8y8u-e6JHx4XnrUrJmwVe0HoxKyR4qSqVhU",1791473819480]