awb-package

Draft a delivery package

Run this skill's commands through the awb MCP tools when the host offers them, as the project's AGENTS.md Commands maps them; the command lines below are the fallback.

Packaging serializes recorded results, reusing evidence, exports, and provenance; changed results require separately authorized analysis. Read the package contract first for layout, consistency rules, and commands. Bundled asset paths are relative to this SKILL.md.

Sequence

1. Establish the investigation, package name, dataset selection, and Audience.
2. Gather the record on the read path the change needs.
3. Write a first pass of findings.md under the contract's Writing rules, with chart specifications, methodology.md, and any methodology-note.md, passing the headline checkpoint.
4. Export the files and provenance with export on every revision, which creates the draft folder; then fill in the display names and paste the methodology_lines, in that order, and review the flags.
5. Review the narratives with a read-only reviewer against every review rule.
6. Check last with check-draft, until done.
7. Report.

1. Establish

Identify the investigation and package. For a correction later drafts could repeat, first ask the user whether later drafts should be checked for it, explaining the check plainly, and record it as a review rule only on their yes, per references/review.md's After the review. If several investigations could fit, ask which before editing. Use the user's package name, else the existing package's, else derive and report a short, stable name from the investigation and a purpose word. Keep one package per investigation unless another has an independent scope or delivery schedule.

From the project root, install the missing shared formats with README's Project interpreter: python3 <awb-init skill directory>/scripts/install_helpers.py . --package-formats, which preserves existing files and records what it installs in .awb-receipt.json.

For a new package, ask which audience-facing datasets to include and explicitly offer none; there is no default export set. When the user narrows the package to some of their questions, list those ledger IDs in the manifest's questions after export, leaving the brief as it is. A revision keeps the current manifest's selection unless the user changes it or it no longer fits the package scope; when it no longer fits, explain why and ask for another before exporting.

Read the investigation brief's Audience: who sees or presents the deck, their knowledge, decision, terms, deck length, and checkpoint mode. If missing or blank, ask and record the answer there (after Purpose when absent) as record maintenance. Record precision and clock format, using the brief template's audience defaults when unspecified; also any stated deck length, methods note length as Methods note length: about <n> words, or checkpoint mode. When it or the request mentions a methods note, ask whether the audience needs methodology-note.md.

2. Gather the record

• New draft or changed analytical scope or results: read the investigation's brief.md, state.md, history.md, settings, run.py, and producers/; the relevant portions of foundation/sources.md, catalog.md, quality.md, and glossary.md; and any draft manifest and latest release.
• Bounded narrative revision, including an omission or accepted caveat: start with the current draft and manifest, the brief's Audience, current findings and flags in state.md, the requested change and the evidence, history, and foundation entries relevant to it, plus the latest release parts and date the changes slide needs. Expand to the other records above wherever scope, evidence, provenance, or consistency is missing or conflicting.

Recover the business question, the manifest's questions when listed, decision or exploratory purpose, audience, usefulness criteria, contract evidence, and limitations and errors affecting interpretation.

Read the ledger with python3 src/awb.py questions list --all and each represented result's recorded settings answers to derive the storyline under the contract's Ledger storyline rules (pass --investigation <name> to commands for another investigation).

When a brief section names a ledger question ID, resolve it with that list. An answered question, answered (provisional) included, supplies its recorded text or linked result's value; answered (awaiting recheck) or answered (provisional, awaiting recheck) leaves it unsettled, as does any other status, missing ID, or failed lookup. The list prints each linked finding's status. When unsettled, ask only if the question is open and its answerer is user, recording the answer with python3 src/awb.py questions answer Q-NNN --text "<answer>" --by "<the user>" before writing; otherwise carry the unsettled element, including any usefulness criterion, in both narratives: in findings.md in the audience's words, naming its owner; its ID only in methodology.md's What makes the answer useful: (or matching) line. Never present it as settled.

3. Write the draft

The headline checkpoint

For each required question whose text is not in the audience's words, set audience wording with python3 src/awb.py questions edit Q-NNN --audience "<wording>", leaving its text unchanged. A question the user wants on the Open questions slide that the decision does not need takes --show, leaving its priority. A new draft, or a changed storyline, passes the checkpoint in the first of these modes that applies: the mode the request states; draft-then-review when the request supplies the storyline or asks for the full draft; the mode the brief's Audience section records; preview-and-wait.

• preview-and-wait: write the title slide and every slide headline in storyline order, the conditional Open questions slide included, to .preview/headlines.md in the draft folder, which no check reads and no release copies; show them with the figures behind each headline that chat has not shown, and write the full slides once the user approves or reorders them.
• draft-then-review: write the full draft and finish the steps below; step 7 reports its headlines.

In either mode a consequential open choice, such as unapproved audience wording or an unsettled usefulness criterion, stops the draft before its full slides and is asked with the headlines. Headlines claim only what results show: no untested cause or label, no exception dropped. Promote each provisional finding behind an approved headline with python3 src/awb.py state finding <result-id> --status supported --reason "<why>".

With the headlines, show the required questions as the slide words them, and state the brief's precision and clock format in the sentence saying the deck opens with a title slide, then the answer slide, and a headline holds at most 15 words. Before trimming a headline the user wrote or approved, ask: offer shorter wording, or theirs with their reason in the manifest's accepted_long_headlines. Report main slides, title included, and appendix slides against any recorded length; propose appendix moves when main slides exceed it. Propose ledger-derived finding order; record an approved alternative as the manifest's presentation_order after export, leaving ledger priority and parent unchanged. Revisions keeping the storyline skip the checkpoint; new audience wording needs approval.

Write the full slides

Write the draft at the contract's paths, or revise the same files: a first pass, which step 4 finishes. A draft in an earlier format is rewritten whole in the current format on its next revision; releases stay frozen.

• findings.md is the deck outline under the slide rules and translation rule in package-format/findings-template.md; its Answer slide is the executive summary.
• Order finding slides by presentation_order, the slide slugs ledger_order lists, when the manifest records one, otherwise under the contract's Ledger storyline rules, which also govern Open questions; slides the user agreed to move go under ## Appendix. Report every finding with no linked ledger question.
• methodology.md follows package-format/methodology-template.md in the workbench's own vocabulary.
• When the audience needs one, methodology-note.md follows package-format/methodology-note-template.md.
• Copy package-format/deck-rules.md unchanged into the draft, and package-format/assembly/m365.md as m365-assembly.md.
• Record facts a revision brings in that the investigation records lack, such as a limitation the user supplies, in its history.md as record maintenance, so no narrative states more than the records. When a review or the user corrects a claim a finding's text states, also reword that finding with python3 src/awb.py state finding <id> --text "<corrected text>" in the same revision.

4. Export the files and provenance

1. Run python3 src/awb.py export <investigation> <package> --chart <result>[:<columns>][@first=<n>|@where=<column>=<value>,...] ... --dataset <name>=<result>[:<columns>] ... (or --no-datasets) --result <id> ..., passing every represented result: one --chart per Chart N. specification, in order, exactly the user-selected datasets, and each other represented result as --result, which is recorded without the export check, so a flagged finding can be represented with its caveat. Choose columns so each file holds exactly what its chart plots, with interval bounds as their own columns, and select its rows in the --chart, such as @first=10 for a top ten, rather than recording a new result. Display choices, such as the highlight or baseline, go in the specification.
2. Give each listed column without a display name one from the glossary: fill its display_stub under [columns] in foundation/display.toml, and paste its round_stub under [round], replacing each "" with the places the brief's precision gives, unquoted, such as "share" = 1. List fractions the slide shows as percents in [percent]'s columns = [...], and name a column that means something else in another result under [results."<id>".columns]; a result whose column of that name already holds percents lists its own percent columns, even none, under [results."<id>".percent]. Fix any blank name or places it reports in place, and rerun. For each label_warnings column, confirm its name suits every result it labels, or name it for one result. Data: lines and dataset headers use these names.
3. Paste its methodology_lines into methodology.md, and repeat each of its questions verbatim in the methodology section of the finding that result supports.
4. For a revision that only adds caveats and keeps the exported files, pass only --result, once for every represented result; omit --chart, --dataset, and --no-datasets. A check-draft charts row that asks to rerun export needs the full export, with every --chart.
5. When export reports exports_blocked, stop and report it. When it reports missing evidence it writes nothing; stop, or rerun and restore, as Missing evidence in numbers and evidence says. Commit nothing on the user's behalf to make provenance look clean.

export records each flag's finding and reason and lists flags_pending. Review every flag's represented_in against the revised draft and fill pending places per the contract; then for any represented flag whose disposition is still none, ask the user to revalidate, omit, or release with the caveat, and record the answer, none until there is one.

5. Review

Once the narratives and flags are complete, run the review in references/review.md: a fresh subagent, limited to read tools, checks the draft against the brief's definitions and questions, every rule in foundation/review-rules.md, and what check-draft cannot check, and reports without fixing; that file's Launch says how each host starts it, right after review-receipt start. Record and act on its report as that file's After the review says.

6. Check

Once every other draft file is final, run python3 src/awb.py check-draft <investigation> <package>. Repair the draft and rerun it; a long-headline warning row is asked about as the headline checkpoint says, never trimmed unasked. When a repair rewrites a sentence the user wrote, show them the new wording, and never call it their wording unless it is word for word theirs. A note_length row is a methods note over the brief's length: shorten it, or report its word count against that length.

A numbers row is a number no represented result records; its problem names the rule that applied. A numbers row on a methodology.md Claim strength: line the claims check refuses clears once that row is repaired: repair it first, never listing its numbers in allowed_numbers. Repair any other numbers row by the first of these that fits:

1. It comes from a recorded result the draft relies on but export was not given: rerun export passing that result too. allowed_numbers never stands in for representing a result.
2. A represented result records it at another value or precision: rewrite it from the recorded value. For another prose unit than its chart or dataset column, give that column a [scale] divisor, such as { divide = 1000, files = false }, in foundation/display.toml and rerun export; for a rounder figure, use a scale word: "22.5 thousand" traces to 22,523.
3. It is not a quantity, such as a date, a comparison year, a chart number, or a tool version: the check reports any number whose context leaves it in doubt, so reword where a context numbers and evidence lists would mark it, such as a comma after a date or year; otherwise, or when the records support it from elsewhere, such as an earlier release, a history.md entry, or a result's question methodology.md repeats, list it in the manifest's allowed_numbers as package-format/manifest-template.md describes.
4. It is computed from results that none records: only separately authorized analysis records it; until then, leave it out.

Done when check-draft prints passed: true on the final files and its review row is current, a passed review, full or scoped, of these files, which checks what check-draft cannot. Any edit after check-draft reruns it. Report its outcome.

7. Report

Report the review's outcome and any problems the user accepted, the package name, the draft path, the audience findings.md is written for, the main and appendix slide counts from check-draft's slides against any recorded length, the included datasets, each chart by what it shows, unresolved caveats, and the check's unlinked_findings. Report a provenance gap, a manifest value recorded as {"unknown": "<reason>"} or a requirements line in a result's unread_requirements, as what went unrecorded, such as "one result's package versions were not recorded", or not at all when it changes nothing the user decides, such as an unrecorded packaging commit in a project without Git or without a commit yet. Suggest no commit in this report when you already suggested a commit this session. When open_questions_count exceeds five, report the count. In draft-then-review, list the slide headlines, marked provisional, with what the headline checkpoint shows beside them, and ask the user to approve or reorder them. Call methodology.md the internal methodology reference, and offer a methodology-note.md when the draft has none. Say it is a working copy the next revision overwrites; marking it delivered freezes it as a numbered release. When a represented flagged finding lacks an applicable disposition, say awb-release will ask for one before releasing.

Point the user to the draft's START-HERE.md: what to send the audience, what builds the deck in a Microsoft 365 Copilot app chat with the PowerPoint agent, and what stays internal.

Delivery milestone

When the user marks the package delivered, invoke `awb-release`. A revision requested with it comes first: finish it, show the user the changed slides, and wait for their yes before invoking awb-release, unless they said to release without seeing it.