From 7f23cc2561f87725d19a30dcdbe3233008f7a278 Mon Sep 17 00:00:00 2001 From: Nicholas Karlson Date: Wed, 14 Jan 2026 00:33:36 -0800 Subject: [PATCH] =?UTF-8?q?Docs:=20standardize=20workbook=20chapter=20page?= =?UTF-8?q?s=20(Ch0=E2=80=93Ch4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../workbook/ch01_equation_transaction.rst | 201 ++++------------ docs/source/workbook/ch01_startup.rst | 219 ++++++------------ .../ch02_journal_to_trial_balance.rst | 160 +++---------- .../workbook/ch03_adjusting_entries.rst | 138 ++++------- .../workbook/ch04_closing_and_post_close.rst | 144 ++++-------- 5 files changed, 234 insertions(+), 628 deletions(-) diff --git a/docs/source/workbook/ch01_equation_transaction.rst b/docs/source/workbook/ch01_equation_transaction.rst index 1fd5a13..4afcfda 100644 --- a/docs/source/workbook/ch01_equation_transaction.rst +++ b/docs/source/workbook/ch01_equation_transaction.rst @@ -3,185 +3,72 @@ Chapter 1: The equation & the transaction **Subtitle:** The physics of business -Before we touch debits/credits, we learn the law that *must* always hold: +Before we touch debits/credits, we learn the law that must always hold: .. math:: \text{Assets} = \text{Liabilities} + \text{Equity} -LedgerLoom exists to enforce this law. +In this workbook, you will draft the work in a spreadsheet, then verify it with LedgerLoom. -In this workbook, you will *draft* the accounting in a spreadsheet, then *verify* -it with LedgerLoom. +What you'll learn +----------------- +- Describe how each business event changes A / L / E +- Translate a business event into a *balanced* journal entry (two or more lines) +- Use LedgerLoom to confirm you didn’t “balance by accident” -Why do this? +What to do in your spreadsheet +------------------------------ +For each event, do two passes: -* A spreadsheet is great for exploration. -* A verifier is great for **proof**. -* When the two agree, you know you didn’t “balance by accident.” +1) **Equation pass**: explain the change in Assets / Liabilities / Equity +2) **Journal pass**: write the corresponding debit/credit lines -The assignment: “Sparkle Cleaners” ----------------------------------- +Export CSVs +----------- +Export (or edit directly) the journal lines: -Scenario -^^^^^^^^ +- ``inputs//transactions.csv`` -On January 1, 2026, Sarah opens **Sparkle Cleaners**, a local cleaning business. +If you are using the workbook project created in Chapter 0, this is already in place. -Record these transactions: - -1. **Jan 1:** Sarah invests **$10,000** cash into the business bank account. -2. **Jan 2:** The business buys cleaning equipment for **$3,000** (paid from the bank). -3. **Jan 3:** The business buys cleaning supplies for **$500** (paid from the bank). - -Your goal -^^^^^^^^^ - -After each transaction, show that the equation remains balanced. - -Draft the solution in Google Sheets ------------------------------------ - -Create a sheet with these asset sub-columns: - -- Cash -- Equipment -- Supplies - -And these right-side columns: - -- Liabilities (none yet in this chapter) -- Equity (Owner capital) - -Work each transaction step-by-step: - -1) Owner investment (Jan 1) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Cash increases by 10,000 (asset up) -- Capital increases by 10,000 (equity up) - -2) Equipment purchase (Jan 2) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Cash decreases by 3,000 -- Equipment increases by 3,000 - -This is a pure asset swap. - -3) Supplies purchase (Jan 3) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Cash decreases by 500 -- Supplies increases by 500 - -The gotcha: asset vs expense ----------------------------- - -Many students instinctively record the $500 as an expense (“we bought stuff to use”). - -For this chapter, treat the supplies as an **asset**: - -- On Jan 3, the supplies are sitting on a shelf. -- They become an expense later, when used up. - -.. admonition:: Translation box — what a spreadsheet hides - - In a spreadsheet, you can “make it balance” by changing a cell. - LedgerLoom won’t let you: the postings must sum to zero, every time. - -Verify with LedgerLoom (v0.2.0 workflow) ----------------------------------------- - -In the *workbook* profile, we verify using the accounting-cycle artifacts that -match what you do in class: - -**transactions.csv → (optional) adjustments.csv → entries → trial balances → closing** - -Step 1 — Initialize a workbook project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: bash - - ledgerloom init --profile workbook sparkle_cleaners - cd sparkle_cleaners - -.. tip:: - - If your terminal can’t find the ``ledgerloom`` command, use: - - .. code-block:: bash - - python -m ledgerloom init --profile workbook sparkle_cleaners - -Step 2 — Add the accounts you need -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Open ``config/chart_of_accounts.yaml`` and make sure it contains at least: - -* ``Assets:Cash`` -* ``Assets:Equipment`` -* ``Assets:Supplies`` -* ``Equity:OwnerCapital`` - -.. admonition:: Keep it simple - - In Chapter 1 we *do not* record expenses yet. Supplies are an **asset** here. - (You’ll see supplies become an expense later, when used up.) - -Step 3 — Enter the journal lines in ``transactions.csv`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Open ``inputs//transactions.csv`` (the folder name is your period, e.g. ``2026-01``) -and enter these lines: - -.. code-block:: text - - entry_id,date,narration,account,debit,credit - T1,2026-01-01,Owner investment,Assets:Cash,10000.00,0.00 - T1,2026-01-01,Owner investment,Equity:OwnerCapital,0.00,10000.00 - T2,2026-01-02,Buy equipment,Assets:Equipment,3000.00,0.00 - T2,2026-01-02,Buy equipment,Assets:Cash,0.00,3000.00 - T3,2026-01-03,Buy supplies,Assets:Supplies,500.00,0.00 - T3,2026-01-03,Buy supplies,Assets:Cash,0.00,500.00 - -Each ``entry_id`` groups the lines of a single transaction. LedgerLoom enforces -that each entry balances. - -Step 4 — Run check, then build -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Run LedgerLoom +-------------- +From your workbook project folder: .. code-block:: bash ledgerloom check --project . ledgerloom build --project . --run-id ch01 -Now open these artifacts under ``outputs/ch01/artifacts/``: - -* ``entries.csv`` (your cleaned, canonical entries) -* ``trial_balance_unadjusted.csv`` - -.. tip:: - - If you are using Excel/Sheets, you can *import* the trial balance CSV and - compare it directly to your spreadsheet totals. +What to look at +--------------- +- ``entries.csv``: what LedgerLoom ingested (grouped by ``entry_id``) +- ``trial_balance_unadjusted.csv``: your “transactions-only” trial balance -Reconciling with your Google Sheet ----------------------------------- +If your spreadsheet totals don’t match the unadjusted trial balance, you have a reconciliation problem +(not a “LedgerLoom problem”). Use :doc:`workbook_troubleshooting`. -Your sheet and LedgerLoom should agree on the ending balances: +Compare against the answer key +------------------------------ +This chapter’s concepts are applied using the same Chapter 0/1 startup dataset. +Use the Ch01 packs if you want a known-good reference: -* Cash = 6,500 -* Equipment = 3,000 -* Supplies = 500 -* OwnerCapital = 10,000 +- :doc:`workbook_check_your_work_pack` -If they don’t match, treat it like a programming bug: +Common mistakes +--------------- +- Treating an asset purchase as an expense (e.g., supplies vs supplies expense) +- Recording one-sided entries (missing the second line) +- Mixing up account roots (Assets vs Expenses vs Equity) +Downloads +--------- +Use the Ch01 startup packs: -* locate the first place the two diverge, -* inspect the transaction lines (wrong account? wrong sign? swapped debit/credit?), -* fix the CSV, -* re-run ``ledgerloom build``. +- :download:`Completed Ch01 spreadsheet (XLSX) <../_static/ledgerloom_workbook_completed_ch01_startup.xlsx>` +- :download:`Reference outputs pack (ZIP) <../_static/ledgerloom_workbook_reference_outputs_ch01_startup.zip>` -That’s the Hybrid Method: **draft fast, verify strict, reconcile to proof**. +Next chapter +------------ +Continue to :doc:`ch02_journal_to_trial_balance`. diff --git a/docs/source/workbook/ch01_startup.rst b/docs/source/workbook/ch01_startup.rst index 4a47f25..cd5fc1c 100644 --- a/docs/source/workbook/ch01_startup.rst +++ b/docs/source/workbook/ch01_startup.rst @@ -1,180 +1,91 @@ -Workbook Chapter 0 — Setup and a Runnable Startup Project -========================================================= +Chapter 0: Setup and a runnable startup project +=============================================== -This chapter is the **setup** chapter. +This setup chapter gets you from **zero → runnable** on Windows, macOS, or Linux. -By the end, you will be able to: +LedgerLoom is not a replacement for your spreadsheet. It’s a verifier: +you draft your work in Sheets/Excel, then LedgerLoom checks the accounting-cycle invariants. -* install LedgerLoom from PyPI on Windows, macOS, or Linux, -* run a known-good example project, -* understand the *inputs → verification → artifacts* workflow, -* and know where to look when something goes wrong. +What you'll learn +----------------- +- Install LedgerLoom from PyPI (student workflow) +- Create a workbook project with ``ledgerloom init --profile workbook`` +- Understand where outputs go (``outputs/check`` vs ``outputs/``) +- Run the end-to-end workflow: inputs → check → build → artifacts -LedgerLoom is not a replacement for your spreadsheet. It’s a verifier. -You do the thinking and drafting in Sheets/Excel; LedgerLoom checks the invariants -(balanced entries, stable totals) and produces canonical artifacts you can compare -to your sheet. +What to do in your spreadsheet +------------------------------ +1) Open the Workbook template (or your course sheet). +2) Enter the “Startup” transactions for the period. +3) (Optional) compute one simple adjustment (e.g., supplies used). -What you need -------------- +Export CSVs +----------- +Export these CSVs from your spreadsheet tabs: -* **Python 3.10+** (3.11 or 3.12 recommended). -* A terminal: +- ``inputs//transactions.csv`` (journal lines) +- ``inputs//adjustments.csv`` (end-of-period adjustments) - * **Windows:** Git Bash (recommended) or PowerShell - * **macOS/Linux:** Terminal +The exact column headers matter. If you’re unsure, use: -Install LedgerLoom (PyPI) -------------------------- +- :download:`Workbook template (XLSX) <../_static/ledgerloom_workbook_template.xlsx>` +- :download:`Template CSV headers (XLSX) <../_static/ledgerloom_workbook_template_csv_headers.xlsx>` -You can install LedgerLoom in two common ways: - -Option A — Virtual environment (recommended for students) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Create a folder for your course work, then: - -.. code-block:: bash - - # create a virtual environment - python -m venv .venv - - # activate it - # macOS/Linux: - source .venv/bin/activate - # Windows (Git Bash): - source .venv/Scripts/activate - - # install LedgerLoom - python -m pip install --upgrade pip - python -m pip install ledgerloom - -Verify: +Run LedgerLoom +-------------- +Create a new workbook project (once): .. code-block:: bash - python -m ledgerloom --help - -Option B — pipx (nice CLI install) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you already use ``pipx`` (it installs CLI tools in isolated environments): - -.. code-block:: bash - - pipx install ledgerloom - ledgerloom --help - -.. admonition:: If you see “command not found” - - Use the module form instead: - - .. code-block:: bash - - python -m ledgerloom --help - -Your first runnable project (in the repo) ------------------------------------------ - -LedgerLoom’s documentation includes a runnable example project in the repository. -This is what keeps the docs honest: the docs literally include the real files. + ledgerloom init --profile workbook my_books + cd my_books -The example lives here:: - - examples/workbook/ch01_startup/ - -Run it ------- - -From the LedgerLoom repository root, you can run the example by pointing -``--project`` at the example folder. +Then verify and build: .. code-block:: bash - python -m ledgerloom check --project examples/workbook/ch01_startup - python -m ledgerloom build --project examples/workbook/ch01_startup --run-id demo - -Where do outputs go? --------------------- - -LedgerLoom writes build artifacts under the project folder: - -* ``outputs//artifacts/`` — CSV artifacts you can open in Excel/Sheets -* ``outputs//manifest.json`` — a “trust manifest” that records file hashes - -For the example above, look in:: - - examples/workbook/ch01_startup/outputs/demo/artifacts/ - -You should see: - -* ``entries.csv`` -* ``trial_balance_unadjusted.csv`` -* ``trial_balance_adjusted.csv`` -* ``closing_entries.csv`` -* ``trial_balance_post_close.csv`` - -.. admonition:: Why “trust manifests” matter - - In accounting (and in real analytics work), you want the same inputs to produce - the same outputs every time. LedgerLoom records hashes of every artifact so you - can prove your build is deterministic. - -Project config: ``ledgerloom.yaml`` ------------------------------------ - -This file declares the project’s build profile (here: ``workbook``), the accounting -period, and where inputs live. - -.. literalinclude:: ../../../examples/workbook/ch01_startup/ledgerloom.yaml - :language: yaml - -Chart of accounts: ``config/chart_of_accounts.yaml`` ----------------------------------------------------- - -The chart of accounts (COA) is the *type system* for your bookkeeping. -LedgerLoom uses it to classify accounts into Assets / Liabilities / Equity / -Revenue / Expenses. - -.. literalinclude:: ../../../examples/workbook/ch01_startup/config/chart_of_accounts.yaml - :language: yaml - -Workbook inputs: ``transactions.csv`` -------------------------------------- + ledgerloom check --project . + ledgerloom build --project . --run-id ch01 -In workbook mode, your “transactions” input is a CSV version of your journal entries. -Each transaction has one or more lines; the lines for a single ``entry_id`` must -balance (debits = credits). +Where outputs go +---------------- +- ``ledgerloom check`` (by itself) writes to ``outputs/check//`` +- ``ledgerloom build --run-id ch01`` writes to ``outputs/ch01/`` and includes: -.. literalinclude:: ../../../examples/workbook/ch01_startup/inputs/2026-01/transactions.csv - :language: text + - ``outputs/ch01/check/`` (the check report for this run) + - ``outputs/ch01/trust/`` (manifest + run metadata) + - ``outputs/ch01/artifacts/`` (the canonical CSV outputs you will compare) -Workbook inputs: ``adjustments.csv`` ------------------------------------- +What to look at +--------------- +Start with these artifacts: -Adjustments are also journal entries (same schema), usually created at period-end. -In Chapter 3, you’ll learn how to compute adjustment amounts in your spreadsheet, -then export them to this CSV. +- ``entries.csv`` (normalized entries LedgerLoom ingested) +- ``trial_balance_unadjusted.csv`` (transactions only) +- ``trial_balance_adjusted.csv`` (transactions + adjustments) +- ``closing_entries.csv`` and ``trial_balance_post_close.csv`` (end-of-cycle) -.. literalinclude:: ../../../examples/workbook/ch01_startup/inputs/2026-01/adjustments.csv - :language: text +For a plain-English guide to each artifact, see :doc:`workbook_artifacts_reference`. -The example README (what students actually do) ----------------------------------------------- +Compare against the answer key +------------------------------ +Every workbook chapter has a canonical dataset under ``examples/workbook//``. +If you want a known-good reference: -.. literalinclude:: ../../../examples/workbook/ch01_startup/README.md - :language: text +- see :doc:`workbook_check_your_work_pack` (completed spreadsheet + reference outputs zips) -Troubleshooting checklist -------------------------- +Common mistakes +--------------- +- Wrong CSV headers (extra spaces, renamed columns) +- Debits/credits not balanced within an ``entry_id`` +- Accounts that don’t match the chart of accounts (typos / wrong root) +- Confusing ``outputs/check`` (standalone check) with ``outputs/`` (build run) -If something fails, check these in order: +Downloads +--------- +- :download:`Completed Ch01 spreadsheet (XLSX) <../_static/ledgerloom_workbook_completed_ch01_startup.xlsx>` +- :download:`Reference outputs pack (ZIP) <../_static/ledgerloom_workbook_reference_outputs_ch01_startup.zip>` -1. **Are you pointing at a project folder?** - ``ledgerloom build`` expects a folder containing ``ledgerloom.yaml``. -2. **Is your CSV comma-separated and UTF-8?** - Export from Sheets as CSV. Don’t use semicolons. -3. **Do debits equal credits per entry_id?** - LedgerLoom will stop if any entry is unbalanced. -4. **Did you activate your virtual environment?** - If you installed LedgerLoom in a venv, you must activate it first. +Next chapter +------------ +Continue to :doc:`ch01_equation_transaction`. diff --git a/docs/source/workbook/ch02_journal_to_trial_balance.rst b/docs/source/workbook/ch02_journal_to_trial_balance.rst index 2a24b5f..de0112b 100644 --- a/docs/source/workbook/ch02_journal_to_trial_balance.rst +++ b/docs/source/workbook/ch02_journal_to_trial_balance.rst @@ -2,145 +2,61 @@ Chapter 2: From journal lines to an unadjusted trial balance ============================================================ In Chapter 1, you proved the accounting equation using a spreadsheet. -In this chapter, you connect that idea to the *double-entry system* you will use -for the rest of the course. +In this chapter, you connect that idea to the double-entry system you will use for the rest of the course. -By the end of this chapter, you will be able to: - -* write balanced journal entries in ``transactions.csv``, -* explain what LedgerLoom’s ``entries.csv`` represents, -* explain what a trial balance is (and what it *isn’t*), -* reconcile your spreadsheet totals to ``trial_balance_unadjusted.csv``. - -What is a journal entry? ------------------------- - -A **journal entry** records one business event. - -* It has **two or more lines**. -* The total debits equal the total credits. -* Each line affects exactly one account. - -LedgerLoom workbook mode stores journal lines in a CSV with these columns: - -* ``entry_id`` — groups the lines that belong to the same transaction -* ``date`` — the transaction date -* ``narration`` — a plain-English description -* ``account`` — an account name from your chart of accounts (e.g. ``Assets:Cash``) -* ``debit`` / ``credit`` — numeric amounts (exactly one should be non-zero per line) - -.. admonition:: The one invariant you never violate - - For each ``entry_id``: - - **sum(debit) == sum(credit)** - - If you violate this, LedgerLoom stops immediately. - -What is a trial balance? ------------------------- - -A **trial balance** is a report that lists every account and its ending balance. - -* It does **not** prove the books are correct. -* It **does** prove that total debits = total credits across the ledger. - -In LedgerLoom workbook mode: - -* **Unadjusted TB** = opening + transactions -* **Adjusted TB** = opening + transactions + adjustments - -The trial balance is a bridge between: - -* your detailed journal lines (what happened), and -* financial statements (the summary view). - -Hands-on workflow +What you'll learn ----------------- +- Write balanced journal entries in ``transactions.csv`` +- Explain what LedgerLoom’s ``entries.csv`` represents +- Explain what a trial balance is (and what it isn't) +- Reconcile your spreadsheet totals to ``trial_balance_unadjusted.csv`` -You can do this chapter in one of two ways: - -* use the runnable example from Chapter 0 and edit the CSVs, or -* create a new workbook project with ``ledgerloom init --profile workbook``. +What to do in your spreadsheet +------------------------------ +1) Enter the chapter’s transactions as journal lines. +2) Ensure each ``entry_id`` is balanced (total debits = total credits). +3) Produce your spreadsheet trial balance. -Option A — Start from the example project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Export CSVs +----------- +Export: -Copy the example folder somewhere you can edit it (so you don’t modify the -LedgerLoom repo itself): +- ``inputs//transactions.csv`` -.. code-block:: bash - - cp -r examples/workbook/ch01_startup ~/ledgerloom_homework/ch02 - cd ~/ledgerloom_homework/ch02 - -Option B — Create a fresh workbook project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: bash - - ledgerloom init --profile workbook ch02_trial_balance - cd ch02_trial_balance - -Either way, you should now have: - -* ``ledgerloom.yaml`` -* ``config/chart_of_accounts.yaml`` -* ``inputs//transactions.csv`` -* ``inputs//adjustments.csv`` - -Step 1 — Fill in ``transactions.csv`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For practice, add 4–6 simple transactions (owner investment, a sale, a purchase, -and a payment). - -Then run: +(Adjustments come in Chapter 3, so ``adjustments.csv`` can be empty for now.) +Run LedgerLoom +-------------- .. code-block:: bash ledgerloom check --project . ledgerloom build --project . --run-id ch02 -Step 2 — Read the artifacts -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Open the folder: - -``outputs/ch02/artifacts/`` - -Start with: - -* ``entries.csv`` — LedgerLoom’s cleaned, canonical view of your journal lines -* ``trial_balance_unadjusted.csv`` — balances by account after transactions +What to look at +--------------- +- ``entries.csv``: normalized entries (LedgerLoom's parse of your journal) +- ``trial_balance_unadjusted.csv``: your transactions-only trial balance -What you are looking for: +For definitions and “how to read it”, see :doc:`workbook_artifacts_reference`. -* Every account you used appears on the trial balance. -* The trial balance “looks like” what your spreadsheet says. +Compare against the answer key +------------------------------ +If you want to confirm your work: -Step 3 — Reconcile to your spreadsheet -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- :doc:`workbook_check_your_work_pack` -In your spreadsheet, you likely have a table with account totals. -That’s exactly what the trial balance is. +Common mistakes +--------------- +- Entry not balanced (LedgerLoom will flag this) +- Using an account that isn't in your chart of accounts +- Sign errors (debit/credit swapped) +- Spreadsheet TB includes an account total that doesn’t tie to your journal lines -If something doesn’t match: - -* Find the account that differs. -* Look at the lines in ``entries.csv`` for that account. -* Check for a swapped debit/credit, a wrong account, or a typo in the amount. - -Common beginner mistakes (and what LedgerLoom catches) ------------------------------------------------------- - -* **Unbalanced entry** (debits ≠ credits): build stops immediately. -* **Unknown account name**: check stops because the COA can’t classify it. -* **Two-sided line** (both debit and credit non-zero): check stops. -* **Sign confusion**: your spreadsheet and LedgerLoom disagree; fix the journal line. +Downloads +--------- +- :download:`Completed Ch02 spreadsheet (XLSX) <../_static/ledgerloom_workbook_completed_ch02_journal_to_trial_balance.xlsx>` +- :download:`Reference outputs pack (ZIP) <../_static/ledgerloom_workbook_reference_outputs_ch02_journal_to_trial_balance.zip>` Next chapter ------------ - -In Chapter 3, you will add **adjusting entries** and learn why the adjusted trial -balance is the real “end-of-period truth” for statements. +Continue to :doc:`ch03_adjusting_entries`. diff --git a/docs/source/workbook/ch03_adjusting_entries.rst b/docs/source/workbook/ch03_adjusting_entries.rst index 74a485c..b837bf4 100644 --- a/docs/source/workbook/ch03_adjusting_entries.rst +++ b/docs/source/workbook/ch03_adjusting_entries.rst @@ -2,109 +2,61 @@ Chapter 3: Adjusting entries and the adjusted trial balance =========================================================== Most businesses do not operate on a pure “cash in / cash out” basis. - -At the end of the period, you record **adjusting entries** to make sure your -records reflect what was *earned* and what was *incurred* during the period. - -By the end of this chapter, you will be able to: - -* explain why adjustments exist (accrual vs. cash), -* compute adjustment amounts in your spreadsheet, -* export those adjustments into ``adjustments.csv``, -* and interpret ``trial_balance_adjusted.csv``. - -The big idea ------------- - -The unadjusted trial balance is “what the ledger says after transactions.” -The adjusted trial balance is “what the ledger says after we apply accrual logic.” - -In class, adjusting entries commonly fall into these buckets: - -* **Deferrals** (cash happens first, expense/revenue happens later) - * prepaid expenses, unearned revenue -* **Accruals** (expense/revenue happens first, cash happens later) - * accrued wages, accrued interest, accounts receivable -* **Estimates** - * depreciation, bad debt expense - -LedgerLoom does not “solve” the adjustment math for you. -That work belongs in your spreadsheet (because that’s where the reasoning lives). -LedgerLoom’s job is to: - -* enforce that each adjustment entry balances, -* apply it consistently to produce the adjusted trial balance, -* preserve the audit trail as versioned CSV artifacts. - -Hands-on: add one adjustment ----------------------------- - -Use the workbook project from Chapter 2 (or the example from Chapter 0). - -Step 1 — Decide your adjustment in the spreadsheet -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Example adjustment: **supplies used**. - -Suppose your spreadsheet says that of the supplies on hand, **$120** were used -in January. - -The adjusting entry is: - -* Debit **Expenses:SuppliesExpense** 120 -* Credit **Assets:Supplies** 120 - -.. admonition:: Why this works - - * The asset (supplies on hand) goes down. - * The expense (supplies consumed) goes up. - -Step 2 — Add accounts to your chart of accounts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If your COA does not already include an expense account for supplies, add one. -For example: - -* ``Expenses:SuppliesExpense`` - -Step 3 — Put the adjustment into ``adjustments.csv`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Open ``inputs//adjustments.csv`` and add: - -.. code-block:: text - - entry_id,date,narration,account,debit,credit - A1,2026-01-31,Supplies used,Expenses:SuppliesExpense,120.00,0.00 - A1,2026-01-31,Supplies used,Assets:Supplies,0.00,120.00 - -Step 4 — Build and compare -^^^^^^^^^^^^^^^^^^^^^^^^^^ - +At the end of the period, you record **adjusting entries** so your books reflect what was earned and incurred. + +What you'll learn +----------------- +- Explain why adjustments exist (accrual vs. cash) +- Compute adjustment amounts in your spreadsheet +- Export adjustments into ``adjustments.csv`` +- Interpret ``trial_balance_adjusted.csv`` + +What to do in your spreadsheet +------------------------------ +1) Start from your Chapter 2 unadjusted trial balance. +2) Compute the adjustment amount(s) (example: supplies used, prepaid expiring, accrued revenue). +3) Write the adjusting journal entry lines. + +Export CSVs +----------- +Export: + +- ``inputs//transactions.csv`` (same as Ch02) +- ``inputs//adjustments.csv`` (new for this chapter) + +Run LedgerLoom +-------------- .. code-block:: bash ledgerloom check --project . ledgerloom build --project . --run-id ch03 -Now compare: +What to look at +--------------- +- ``trial_balance_unadjusted.csv``: before adjustments +- ``trial_balance_adjusted.csv``: after adjustments -* ``outputs/ch03/artifacts/trial_balance_unadjusted.csv`` -* ``outputs/ch03/artifacts/trial_balance_adjusted.csv`` +Your spreadsheet’s adjusted trial balance should match LedgerLoom’s adjusted trial balance +account-by-account (within rounding rules you control in the spreadsheet). -You should see: +Compare against the answer key +------------------------------ +If you want a known-good reference: -* Supplies (asset) is **$120 lower** after the adjustment. -* SuppliesExpense (expense) appears with a **$120 debit balance**. +- :doc:`workbook_check_your_work_pack` -Common adjustment mistakes --------------------------- +Common mistakes +--------------- +- Putting adjustments in ``transactions.csv`` instead of ``adjustments.csv`` +- Using the wrong date (adjustments are typically period-end) +- Adjusting the wrong account (asset vs expense) +- Recording the right adjustment with the wrong sign -* **Forgetting to add the account to the COA** → LedgerLoom can’t classify it. -* **Putting the adjustment in transactions.csv** → keep transactions and adjustments separate. -* **Reversing debit/credit** → the adjusted TB moves in the wrong direction. +Downloads +--------- +- :download:`Completed Ch03 spreadsheet (XLSX) <../_static/ledgerloom_workbook_completed_ch03_adjusting_entries.xlsx>` +- :download:`Reference outputs pack (ZIP) <../_static/ledgerloom_workbook_reference_outputs_ch03_adjusting_entries.zip>` Next chapter ------------ - -In Chapter 4, you will close temporary accounts and produce a **post-close trial -balance** that contains only balance sheet accounts. +Continue to :doc:`ch04_closing_and_post_close`. diff --git a/docs/source/workbook/ch04_closing_and_post_close.rst b/docs/source/workbook/ch04_closing_and_post_close.rst index 3d4d972..59b7d5e 100644 --- a/docs/source/workbook/ch04_closing_and_post_close.rst +++ b/docs/source/workbook/ch04_closing_and_post_close.rst @@ -1,125 +1,65 @@ Chapter 4: Closing entries and the post-close trial balance =========================================================== -At the end of an accounting period, you “reset” the temporary accounts. +Closing is how we reset the income statement accounts (Revenue and Expenses) to zero +so the next period starts clean, while moving net income into equity. -Temporary accounts include: - -* Revenues -* Expenses -* Dividends / Draws (depending on the business form) - -The goal is to move the period’s net result into **Retained Earnings** (or the -equity-equivalent in your COA), so the next period starts clean. - -In LedgerLoom workbook mode, you do **not** hand-write closing entries in a CSV. -Instead, LedgerLoom generates them deterministically from your **adjusted trial -balance**. - -By the end of this chapter, you will be able to: - -* explain what “closing” means and why we do it, -* read ``closing_entries.csv``, -* read ``trial_balance_post_close.csv``, -* and understand the Balance-Sheet-only invariant. - -What LedgerLoom generates -------------------------- - -When you run a workbook build, LedgerLoom emits two end-of-cycle artifacts: - -* ``closing_entries.csv`` — a set of closing entries with ``entry_kind="closing"`` -* ``trial_balance_post_close.csv`` — a post-close TB that contains only - **Assets / Liabilities / Equity** accounts - -This is a powerful learning tool: - -* You can compare LedgerLoom’s generated closing entries to your textbook’s “income summary” method. -* You can verify that all temporary accounts are truly zeroed out. - -Hands-on workflow +What you'll learn ----------------- +- Explain what “closing” means and why we do it +- Read ``closing_entries.csv`` +- Read ``trial_balance_post_close.csv`` +- Understand the Balance-Sheet-only invariant -Use the same workbook project you used for Chapters 2–3. - -Step 1 — Ensure you have at least one Revenue and one Expense -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Closing is only interesting if you have temporary accounts. - -If your project doesn’t yet include revenue/expense accounts, add a simple sale and an expense. -For example: - -* Add to COA: - - * ``Revenue:ServiceRevenue`` - * ``Expenses:SuppliesExpense`` (or any expense you used) +What to do in your spreadsheet +------------------------------ +1) Confirm your adjusted trial balance is correct (Chapter 3). +2) Compute net income (revenues - expenses). +3) Draft closing entries in the spreadsheet (or follow your course method). -* Add a sale transaction (example): +Export CSVs +----------- +Export: - .. code-block:: text +- ``inputs//transactions.csv`` +- ``inputs//adjustments.csv`` - T4,2026-01-05,Cleaning service paid in cash,Assets:Cash,300.00,0.00 - T4,2026-01-05,Cleaning service paid in cash,Revenue:ServiceRevenue,0.00,300.00 - -Now rebuild: +(Closing entries are generated by LedgerLoom from the adjusted trial balance in workbook mode.) +Run LedgerLoom +-------------- .. code-block:: bash ledgerloom check --project . ledgerloom build --project . --run-id ch04 -Step 2 — Read ``closing_entries.csv`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Open: - -``outputs/ch04/artifacts/closing_entries.csv`` - -You should see: - -* revenue accounts debited to bring them to zero, -* expense accounts credited to bring them to zero, -* the net difference posted to ``Equity:RetainedEarnings``, -* dividends/draws closed to retained earnings (not through income summary). - -.. admonition:: Dividends are not an expense - - Dividends reduce equity, but they do not reduce *income*. - That’s why LedgerLoom closes dividends/draws directly to retained earnings. - -Step 3 — Read ``trial_balance_post_close.csv`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +What to look at +--------------- +- ``closing_entries.csv``: generated closing entries (entry_kind = closing) +- ``trial_balance_post_close.csv``: post-close TB (only Assets / Liabilities / Equity) -Open: +The key invariant: the post-close TB must contain **no Revenue or Expense** accounts. +If it does, something in the closing step is wrong. -``outputs/ch04/artifacts/trial_balance_post_close.csv`` +Compare against the answer key +------------------------------ +If you want a known-good reference: -This trial balance should contain **only**: +- :doc:`workbook_check_your_work_pack` -* Assets -* Liabilities -* Equity (excluding dividends/draws) +Common mistakes +--------------- +- Revenue/Expense accounts still present after closing (should be zeroed out) +- Using the wrong equity account for net income (depends on your course) +- Forgetting that closing happens *after* adjustments +- Confusing “cash basis” intuition with accrual-period reporting -If you still see Revenue or Expenses here, something is wrong: the books are not “reset.” - -The invariant LedgerLoom enforces ---------------------------------- - -LedgerLoom enforces a strict “system reset” invariant: - -* After closing, all Revenue and Expense balances must be exactly zero. -* After closing, Dividends/Draws must be exactly zero. - -If the invariant fails, the build fails. That’s intentional: it prevents you from -carrying temporary balances into the next period. +Downloads +--------- +- :download:`Completed Ch04 spreadsheet (XLSX) <../_static/ledgerloom_workbook_completed_ch04_closing_and_post_close.xlsx>` +- :download:`Reference outputs pack (ZIP) <../_static/ledgerloom_workbook_reference_outputs_ch04_closing_and_post_close.zip>` Where we go next ---------------- - -With Chapters 1–4 in place, you now have the full *spine* of the accounting cycle: - -transactions → unadjusted TB → adjustments → adjusted TB → closing → post-close TB - -Later workbook chapters will build financial statements and introduce “gotcha detectors” -that catch common student errors early. +From here, you can branch into practical bookkeeping subsystems (AR/AP/inventory) or build additional +workbook chapters. See :doc:`workbook_learning_path`.