{"id":"cca670e1-0bad-4e42-9716-56bbb7dbadd8","shortId":"PPPrhZ","kind":"skill","title":"atomic-post-await-state-commit","tagline":"After awaiting persistence work, update the shared budget state for each `tool_use_id` exactly once so no concurrent reader ever sees a half-committed decision.","description":"# SKILL: Atomic Post-Await State Commit\n**Domain:** tool-orchestration  \n**Trigger:** Use this pattern when concurrently persisting large tool results and mutating `ContentReplacementState` once the awaited work completes, such as the `freshReplacements` loop inside `enforceToolResultBudget`.\n**Source Pattern:** Distilled from reviewed tool-loop and result-shaping patterns.\n\n## Core Method\nAwait all selected persistence jobs, then in the same synchronous loop mark each `tool_use_id` as seen and, if persistence succeeded, place the preview string into both the local replacement map and the shared `ContentReplacementState.replacements`. The state mutation happens after the await so other threads or resumed contexts never observe the ID as seen without its replacement (or vice versa), keeping the decision atomic.\n\n## Key Rules\n- Never add a `tool_use_id` to `seenIds` before the persist promise resolves; doing so risks another thread classifying the ID as frozen while the replacement string has yet to materialize.\n- Mark the ID as seen even when persistence fails so the failure case still freezes the original content and prevents reprocessing the same bytes later.\n- When persistence succeeds, update `state.replacements` and `replacementMap` together so immediate replays see the cached preview string with the same bytes that triggered the log/event.\n- Keep the loop synchronous after the await; avoid spreading the state updates across callbacks or other async code paths that might observe partial state.\n\n## Example Application\nInside `enforceToolResultBudget`, `freshReplacements` combines each candidate with the result of `buildReplacement`. The for-loop that follows immediately adds every candidate to `state.seenIds`, then conditionally sets `state.replacements` if a preview exists. That ensures when the same `tool_use_id` reappears (for example during a resume or in a forked agent) the code re-applies the cached preview without re-persisting the file.\n\n## Anti-Patterns (What NOT to do)\n- Do not call `state.seenIds.add` before awaiting persistence; the race can produce `mustReapply` entries without a matching cached preview.\n- Do not leave the replacements map empty after a successful persist; otherwise `applyToolResultBudget` will treat the ID as seen-but-unreplaced and may persist it again later.\n- Do not split the success and failure branches across multiple awaits or microtasks; the observer must never see a `seen` entry without the corresponding replacement when one exists.","tags":["atomic","post","await","state","commit","cskill","agents","ychampion","agent-skills","ai-agents","cli","coding-agents"],"capabilities":["skill","source-ychampion","skill-atomic-post-await-state-commit","topic-agent-skills","topic-ai-agents","topic-cli","topic-coding-agents","topic-context-engineering","topic-developer-tools","topic-mcp","topic-multi-agent","topic-terminal-ui"],"categories":["cskill-agents"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/ychampion/cskill-agents/atomic-post-await-state-commit","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add ychampion/cskill-agents","source_repo":"https://github.com/ychampion/cskill-agents","install_from":"skills.sh"}},"qualityScore":"0.467","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 34 github stars · SKILL.md body (2,518 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T06:56:44.947Z","embedding":null,"createdAt":"2026-04-18T22:19:45.252Z","updatedAt":"2026-04-22T06:56:44.947Z","lastSeenAt":"2026-04-22T06:56:44.947Z","tsv":"'across':244,383 'add':153,276 'agent':307 'anoth':168 'anti':323 'anti-pattern':322 'appli':312 'applic':257 'applytoolresultbudget':359 'async':248 'atom':2,35,149 'atomic-post-await-state-commit':1 'avoid':239 'await':4,8,38,60,85,127,238,334,385 'branch':382 'budget':14 'buildreplac':268 'byte':206,227 'cach':221,314,345 'call':331 'callback':245 'candid':263,278 'case':195 'classifi':170 'code':249,309 'combin':261 'commit':6,32,40 'complet':62 'concurr':25,50 'condit':282 'content':200 'contentreplacementst':57 'contentreplacementstate.replacements':120 'context':133 'core':83 'correspond':398 'decis':33,148 'distil':72 'domain':41 'empti':353 'enforcetoolresultbudget':69,259 'ensur':290 'entri':341,395 'even':188 'ever':27 'everi':277 'exact':21 'exampl':256,299 'exist':288,402 'fail':191 'failur':194,381 'file':321 'follow':274 'for-loop':270 'fork':306 'freez':197 'freshreplac':66,260 'frozen':174 'half':31 'half-commit':30 'happen':124 'id':20,100,137,157,172,185,296,363 'immedi':217,275 'insid':68,258 'job':89 'keep':146,232 'key':150 'larg':52 'later':207,374 'leav':349 'local':114 'log/event':231 'loop':67,77,95,234,272 'map':116,352 'mark':96,183 'match':344 'materi':182 'may':370 'method':84 'microtask':387 'might':252 'multipl':384 'must':390 'mustreappli':340 'mutat':56,123 'never':134,152,391 'observ':135,253,389 'one':401 'orchestr':44 'origin':199 'otherwis':358 'partial':254 'path':250 'pattern':48,71,82,324 'persist':9,51,88,105,162,190,209,319,335,357,371 'place':107 'post':3,37 'post-await':36 'prevent':202 'preview':109,222,287,315,346 'produc':339 'promis':163 'race':337 're':311,318 're-appli':310 're-persist':317 'reader':26 'reappear':297 'replac':115,142,177,351,399 'replacementmap':214 'replay':218 'reprocess':203 'resolv':164 'result':54,80,266 'result-shap':79 'resum':132,302 'review':74 'risk':167 'rule':151 'see':28,219,392 'seen':102,139,187,366,394 'seen-but-unreplac':365 'seenid':159 'select':87 'set':283 'shape':81 'share':13,119 'skill':34 'skill-atomic-post-await-state-commit' 'sourc':70 'source-ychampion' 'split':377 'spread':240 'state':5,15,39,122,242,255 'state.replacements':212,284 'state.seenids':280 'state.seenids.add':332 'still':196 'string':110,178,223 'succeed':106,210 'success':356,379 'synchron':94,235 'thread':130,169 'togeth':215 'tool':18,43,53,76,98,155,294 'tool-loop':75 'tool-orchestr':42 'topic-agent-skills' 'topic-ai-agents' 'topic-cli' 'topic-coding-agents' 'topic-context-engineering' 'topic-developer-tools' 'topic-mcp' 'topic-multi-agent' 'topic-terminal-ui' 'treat':361 'trigger':45,229 'unreplac':368 'updat':11,211,243 'use':19,46,99,156,295 'versa':145 'vice':144 'without':140,316,342,396 'work':10,61 'yet':180","prices":[{"id":"b8b6606f-f4ca-4b4b-9821-9c84c3ac3503","listingId":"cca670e1-0bad-4e42-9716-56bbb7dbadd8","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"ychampion","category":"cskill-agents","install_from":"skills.sh"},"createdAt":"2026-04-18T22:19:45.252Z"}],"sources":[{"listingId":"cca670e1-0bad-4e42-9716-56bbb7dbadd8","source":"github","sourceId":"ychampion/cskill-agents/atomic-post-await-state-commit","sourceUrl":"https://github.com/ychampion/cskill-agents/tree/main/skills/atomic-post-await-state-commit","isPrimary":false,"firstSeenAt":"2026-04-18T22:19:45.252Z","lastSeenAt":"2026-04-22T06:56:44.947Z"}],"details":{"listingId":"cca670e1-0bad-4e42-9716-56bbb7dbadd8","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"ychampion","slug":"atomic-post-await-state-commit","github":{"repo":"ychampion/cskill-agents","stars":34,"topics":["agent-skills","ai-agents","cli","coding-agents","context-engineering","developer-tools","mcp","multi-agent","terminal-ui"],"license":"mit","html_url":"https://github.com/ychampion/cskill-agents","pushed_at":"2026-04-04T14:13:23Z","description":"Agent skills for coding CLIs, multi-agent runtimes, context engines, MCP extensions, and terminal tooling. Instead of using claude code's source code, give your agent skills to create your own!","skill_md_sha":"1956752f46e0b2873d5c75cf2fb79ff348ae9d5a","skill_md_path":"skills/atomic-post-await-state-commit/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/ychampion/cskill-agents/tree/main/skills/atomic-post-await-state-commit"},"layout":"multi","source":"github","category":"cskill-agents","frontmatter":{"name":"atomic-post-await-state-commit","description":"After awaiting persistence work, update the shared budget state for each `tool_use_id` exactly once so no concurrent reader ever sees a half-committed decision."},"skills_sh_url":"https://skills.sh/ychampion/cskill-agents/atomic-post-await-state-commit"},"updatedAt":"2026-04-22T06:56:44.947Z"}}