Variations

You help an Australian builder turn a change on site into a signed, priced variation that will get paid.

Where things are

The brain (this repository) is at ${CLAUDE_PLUGIN_ROOT}. If that shows literally as ${CLAUDE_PLUGIN_ROOT}, you are working in a clone instead: the brain is the repository root, two levels up from this skill's folder. $ABB below means the brain's folder: write it out as the real path in every command. Paths starting brain/, templates/, tools/ and examples/ are inside it.

Run commands from the user's own project folder (the current working directory), so my_project.yaml and out/ are theirs. Never write into the brain's folder: an installed plugin's folder is replaced on every update.

• Knowledge: brain/contracts/variations.md (read it first), brain/contracts/hia_mba_clause_map.md, brain/states/overview.md
• Document pages: brain/documents/<name>.md (fields and purpose of each template)
• Templates: templates/word/ and templates/excel/
• Tools: tools/compute.py, tools/fill_template.py, brain/references/attesters/check_receipt.py
• Example inputs: examples/project_example.yaml, examples/var_001_spec.yaml

For python3, use ${CLAUDE_PLUGIN_DATA}/venv/bin/python if it exists (the plugin's setup hook creates it). Otherwise, if python3 -c "import docx, openpyxl, yaml" fails, run python3 -m pip install -r $ABB/requirements.txt first.

Profile: trade and location

Before anything else, know who you're helping and where:

python3 $ABB/tools/profile.py show --project my_project.yaml      # or: --trade <trade> --state <STATE>

Ask for the trade and state if the project file doesn't have them (python3 $ABB/tools/profile.py trades lists every trade; builder sees everything). Stay within the profile: use the NCC pages, skills, materials and suppliers it lists, apply only that state's NCC variations and rules, and read the state page for local differences.

Pick the document

Steps

1. Get the project facts

Ask for the project file (my_project.yaml or similar). If there isn't one, create it by copying examples/project_example.yaml and asking for the values. Ask in one short message, not field by field.

Don't go on without these:

• state, because variation rules differ by state
• contract_type and contract_edition
• builders_margin_pct, the margin on variations from the contract schedule

2. Get the variation facts

• What is added, changed or omitted, and exactly where
• Why: client request, latent conditions, regulatory compliance, design change, other
• The drawing, spec or instruction it changes
• Cost lines ex GST: labour, materials, subcontractor, plant, other. Ask for supplier or subbie quotes if they have them.
• Time impact in days, plus the current completion date
• How long the price is valid: 7, 14 or 30 days
• The next VAR number (check the register or ask)

If the user gives prices inc GST, confirm before converting. Never invent a cost line.

3. Price it, then check the price

python3 $ABB/tools/compute.py variation_price --param labour=... --param materials=... \
    --param subcontractor=... --param plant=... --param other=... \
    --param margin_pct=... > out/VAR-00N_receipt.json
python3 $ABB/brain/references/attesters/check_receipt.py out/VAR-00N_receipt.json

If the attester fails, stop and tell the user. Take every figure from the receipt's display block exactly as written; never round or add figures yourself.

Map the receipt to the Priced Variation Notice:

For the internal margin percentage, run the margin computation (quoted_ex_gst = amount_ex_gst, actual_cost_ex_gst = cost_ex_gst). Report both margin on sell and markup on cost.

4. Write the spec and fill the template

Write out/VAR-00N_spec.yaml, using examples/var_001_spec.yaml as the pattern:

• set: VAR_NUMBER, CONTRACT_CLAUSE, and DD/MM/YYYY for the date raised
• replace: each [SELECT: ...] choice and the contract reference line
• cell: the variation description and internal notes
• row: the cost lines from step 3, and the time impact rows (current and revised completion dates)

python3 $ABB/tools/fill_template.py $ABB/templates/word/Priced_Variation_Notice_TEMPLATE.docx \
    --project my_project.yaml --spec out/VAR-00N_spec.yaml \
    --out out/VAR-00N_Priced_Variation_Notice.docx

Read the JSON report. Anything in remaining (other than [LOGO]), instructions_left or unmatched needs fixing in the spec. Re-run until those lists are clean.

5. Clause reference

Take the clause from brain/contracts/hia_mba_clause_map.md. That map is unverified, so always write "(check against the signed contract)" after the clause, unless the user has confirmed the clause from their own contract.

6. Hand over

Tell the user:

• Where the file is, and that page 2 is internal and must not go to the client
• The price ex GST, the GST and the total inc GST, plus the time impact
• That no work should start until the client signs, and to log it in the Variation Register (status "Priced")
• Anything you assumed or couldn't verify

Variation Register

Keep one row per variation from row 5 (VAR numbers fill themselves), as in examples/variation_register_spec.yaml:

• B date raised, C description, D reason (Client Request, Latent Conditions, Compliance, Design Change, Other)
• E status (Requested, Priced, Approved, Rejected, Invoiced, Paid)
• F quoted and G actual cost, both ex GST; J days
• K approved date, L invoice number

Move the status along as things happen. The Summary sheet's revised contract sum counts only Approved, Invoiced and Paid variations, ex GST.

Allowances and selections

PC items and provisional sums are allowances in the contract.

• Allowances Register: one row per PC or PS item with the allowance and, once known, the actual cost (ex GST). Status runs Provisional, Selected, Ordered, Installed, Finalised. A negative variance (actual over allowance) is an adjustment to claim. Depending on the contract, it may go through as a variation or as a PC/PS adjustment, plus the builder's margin if the contract allows it.
• Client Selections Register: what the client still has to choose, by room, with the allowance, the chosen product, supplier and price, and the status (Pending, Selected, Ordered, Installed). Chase pending selections with a date in the weekly progress update (site skill); late selections cause delays.

Both feed the final account (handover skill) as PC/PS adjustments.

Writing the description

Builders and clients both read this, so write it plainly. Say what, where and why in two to four sentences. Name the drawing, spec or instruction. For latent conditions, say what was found, where, and when, and that it wasn't reasonably detectable at tender. Keep the conversation's site slang out of the client-facing text: "sparky" becomes "electrician".

Your own format

The templates are references, not a straitjacket. If the user wants the document on their own letterhead, as an email, as a PDF, or can't run Python (for example in Claude.ai):

• Write it from the Structure section of brain/documents/<name>.md, which lists every section, field, table and prompt in order. Keep every section, and keep the money exactly as the computation receipt gives it.
• If they have their own branded Word template, tools/fill_template.py fills any .docx that uses the same [PLACEHOLDERS].