Month End Close

Orchestrate and validate the full month-end close for a QBO client. Reads client SOP, runs automated close checks, scores each item, proposes journal entries...

Security Scan

The skill's instructions claim to run a QBO-connected month-end close but omit the code, binaries, and credentials that such work requires, producing a mismatch that warrants caution before installing or running it.

Purpose & Capability

The SKILL.md describes an automated QBO month-end close pipeline (calls a Python script, runs QBO reports, reads client SOPs, writes Excel and cache files). However, the skill package contains no code, no install spec, no required binaries, and declares no QBO credentials or CLI as required — all of which would normally be necessary for the stated functionality. This is an incoherence: either the instructions assume an external repo/environment, or the package is incomplete or mispackaged.

Instruction Scope

Runtime instructions tell the agent to run `python3 scripts/pipelines/month-end-close.py` and to call `qbo report tb`, read local files at clients/{slug}/sop.md, and read/write cache files under .cache and an Excel workbook to ~/Desktop. Those actions involve accessing local project files and an external QBO integration. The SKILL.md gives the agent broad authority to read local SOPs and cache and to invoke a QBO CLI, but the skill does not declare or provide those artifacts, nor does it limit what else the script might do — creating a scope mismatch and potential surprise if the referenced script were present.

Install Mechanism

This is an instruction-only skill with no install spec (lowest install risk). However, it references a local Python script and a QBO CLI. Because no code or install instructions are included, the skill either expects a preexisting environment (undeclared) or is incomplete. The lack of an install mechanism is coherent from a safety perspective but increases operational ambiguity.

Credentials

No environment variables, credentials, or config paths are declared, yet the workflow clearly needs QuickBooks Online credentials or a configured QBO CLI and access to client SOP files. The absence of declared credentials is disproportionate to the described integration and leaves unclear where/how the skill will obtain access to QBO data.

Persistence & Privilege

The skill is not always-enabled and uses default autonomous invocation settings. It writes cache and workbook files in user-local paths (.cache and ~/Desktop) which is expected for this kind of tool. The skill does not request system-wide or cross-skill configuration changes in the provided instructions.

What to consider before installing

This skill looks like a wrapper for an existing month-end pipeline, but the package is incomplete or mispackaged. Before installing or running: (1) Verify the skill's source and obtain the referenced repository (scripts/pipelines/month-end-close.py) — do not run unknown scripts. (2) Confirm where QBO credentials/QBO CLI come from; prefer least-privilege read-only credentials or a sandbox QBO account for testing. (3) Inspect the referenced script(s) to see exactly what files and endpoints they read/write, and whether they send data externally. (4) Run the pipeline in an isolated environment (VM/container) and with non-production credentials first. (5) If you intend to allow the skill to access client SOPs or desktops, ensure those paths are expected and do not contain unrelated secrets. If you cannot obtain the upstream code or a trustworthy repo/source, treat the skill as incomplete and avoid enabling it.

Month-End Close Checklist — SKILL.md

Orchestrates and validates the full month-end close for a QBO client. Reads clients/{slug}/sop.md to determine which checks apply, runs automated close checks against QBO, scores each item, proposes journal entries for missing items, tracks progress with CDC, and outputs a controller-ready Excel workbook.

---

Trigger

Use this skill when:

• User says "run close", "month-end close", "close checklist", or "close [client] for [month]"
• Monthly close workflow is needed for any QBO-connected client
• Re-running close to check if open items have been resolved

Do NOT use for:

• P&L variance analysis → use pl-quick-compare or pl-deep-analysis
• Bank reconciliation only → use bank-reconciliation
• Budget vs. actual → use budget-vs-actual

---

Script Location

scripts/pipelines/month-end-close.py

---

Usage

# Standard close run
python3 scripts/pipelines/month-end-close.py --slug sb-paulson --month 2026-03

# Skip GL drill (faster; prepaid/depr/payroll checks have limited data)
python3 scripts/pipelines/month-end-close.py --slug willo-salons --month 2026-02 --skip-gl

# Re-run as items get resolved (CDC tracks progress between runs)
python3 scripts/pipelines/month-end-close.py --slug glowlabs --month 2026-03

# Force fresh QBO pulls (ignore CDC cache)
python3 scripts/pipelines/month-end-close.py --slug sb-paulson --month 2026-03 --rerun

# Custom output directory
python3 scripts/pipelines/month-end-close.py --slug sb-paulson --month 2026-03 --out ~/Desktop/close

# QBO Sandbox
python3 scripts/pipelines/month-end-close.py --slug sb-paulson --month 2026-03 --sandbox

---

Arguments

Argument	Required	Description
--slug	✅	Company slug (must match qbo-client connection)
--month	✅	Close period in YYYY-MM format (e.g. 2026-03)
--skip-gl	❌	Skip GL pull — faster but prepaid/depr/payroll checks limited
--rerun	❌	Force all checks fresh — ignores CDC state for check selection
--out	❌	Output directory (default: ~/Desktop)
--sandbox	❌	Use QBO sandbox environment

---

Close Checks

Check	ID	Default	SOP Override
Bank Reconciliation	bank_recon	✅	Disable: bank reconciliation: ❌
Trial Balance (D=C)	trial_balance	✅	Always enabled
AP Aging	ap_aging	✅	Disable: ap aging: ❌
AR Aging	ar_aging	✅	Auto-disabled if SOP says no AR/POS
Prepaid Amortization	prepaid_amortization	✅	Disable: prepaid: ❌
Depreciation	depreciation	✅	Disable: no fixed assets
Payroll Reconciliation	payroll_recon	✅	Disable: payroll: ❌
Revenue Recognition	revenue_recognition	✅	Disable: deferred revenue: ❌
Accrued Expenses	accrued_expenses	✅	Disable: accruals: ❌
Intercompany Eliminations	intercompany	❌ OFF	Enable: multi-entity or intercompany: ✅

---

SOP Integration

The pipeline reads clients/{slug}/sop.md and parses it for:

• AR Aging — auto-disabled if SOP contains: no accounts receivable, POS collection, AR aging: ❌, or AR: Not applicable
• Intercompany — disabled by default; enabled if SOP contains: multi-entity, intercompany: ✅, or consolidated
• Watch notes — special SOP signals become tab notes in Excel (e.g. interest expense, cash burn, deferred revenue, SAFE)

Client SOP Quick Reference

Client	AR?	Interco?	Notes
willo-salons	❌ No	❌ No	POS/cash — no AR
glowlabs	❌ No	❌ No	Gaming/Web3; high burn
sb-paulson	✅ Verify	❌ No	Advisory; watch interest expense
opdo	Check SOP	❌ No	Review SOP

---

Outputs

Excel Workbook

Saved to ~/Desktop/MonthEndClose_{slug}_{YYYY-MM}_Run{N}.xlsx

Tab	Contents
Close Checklist	Dashboard — PASS/FAIL/ACTION per item + completion % + proposed JE count
Trial Balance	Full TB with debit/credit validation, per-account rows, totals
Proposed Entries	All JEs needed for missing/flagged items, sorted HIGH→MEDIUM→LOW
CDC Log	Status changes between runs — tracks close progress over time

Completion Score

Completion % = (PASS + N/A) / Total × 100
Close is "READY" when FAIL = 0 and ACTION = 0

Proposed JE Format

Each proposed entry has:

• Debit Account
• Credit Account
• Amount (Decimal; "TBD" if unknown)
• Memo / basis
• Urgency: HIGH | MEDIUM | LOW

---

CDC (Change Data Capture)

Cache file: .cache/month-end-close/{slug}-{YYYY-MM}.json

• First run: full snapshot saved, no delta
• Subsequent runs: shows status changes (FAIL→PASS = "Resolved ✅", PASS→FAIL = "Regressed ⚠️")
• Re-run the pipeline as items are resolved — CDC tracks progress automatically
• Use --rerun to force fresh QBO pulls without clearing CDC history

---

Check Logic Summary

Bank Recon

Checks .cache/bank-reconciliation/{slug}.json for a completed reconciliation matching the close period end date. If found and is_reconciled: true → PASS. If different period or missing → ACTION NEEDED with command to run.

Trial Balance

Pulls QBO TB report via qbo report tb, sums all debit and credit columns, validates |debits - credits| < $0.02. OUT OF BALANCE → FAIL with proposed suspense entry.

AP / AR Aging

Scans QBO Balance Sheet for AP/AR account balances. Flags material balances ≥ $500 as ACTION NEEDED. Proposes accrual entry for largest outstanding item > $2,500.

Prepaid Amortization

Compares prior-month BS prepaid balances to current. If prior balance > $0 and no GL activity or balance reduction → ACTION NEEDED with estimated monthly amort entry (straight-line over 12 months as placeholder).

Depreciation

Checks fixed asset accounts on BS + scans GL for depreciation/journal entries to accumulated depreciation accounts. No activity on period with known fixed assets → ACTION NEEDED.

Payroll Reconciliation

Sums payroll GL accounts for current period, compares to prior P&L payroll total. Flags if variance > $500 or > 15% month-over-month.

Revenue Recognition

Checks deferred revenue BS balance for movement. No change with known balance → ACTION NEEDED with estimated recognition entry (straight-line over 12 months as placeholder).

Accrued Expenses

Compares accrual account balances prior-vs-current. Flags individual account changes ≥ $1,000 or near-zero reversal from significant balance.

Intercompany

Only runs if enabled by SOP. Checks for non-zero intercompany/due-to/due-from balances. Net balance ≠ $0.02 → ACTION NEEDED with elimination entry.

---

Dependencies

• Python 3.10+ with openpyxl (pip install openpyxl)
• Node.js QBO client with valid auth tokens
• Client SOP at clients/{slug}/sop.md (optional but recommended)
• Completed bank-recon run for bank_recon check to PASS

---

Related Pipelines

Pipeline	Script	Use
P&L Quick Compare	pl-quick-compare.py	Revenue/expense variance
P&L Deep Analysis	pl-deep-analysis.py	GL drill-down + accrual proposals
Bank Reconciliation	bank-reconciliation.py	Must complete before close PASS

Bank Recon must be run first — month-end-close reads its CDC cache to verify completion.

---

Notes

• All financial math uses Python Decimal for precision
• Proposed JE amounts marked "TBD" when determination requires human review (e.g. depreciation schedule)
• SOP parsing is additive: missing SOP = all checks enabled with defaults
• Run multiple times freely — CDC log accumulates close progress history