Form 8949 and data collection documentation (#67)

Add user documentation for gathering inputs
Doc for collecting converted share qty

Support lossy lots forced to balanced
We're enjoined from realizing capital loss. I'm assuming that
applies at a per-share level absent explicit documentation
otherwise.
This allows for exploring forcing any lossy lots to balanced
state instead so that loss can be preserved through future
basis adjustment.
Not exposed via menu or tweaks.

Adds f8949 section to ESPP & RSU datasheets.
Various UX updates to make transcription of f8949 data easier:
* alternate colours for rows
* duplicate presentation of cash proceeds and date in format
  matching Turbotax
* bolds the lines around the section for attention

Restores Close as a valid FMV value.
Adds placeholders for 1099-B data import.
Minor changes to remove spurious formatting.

Clarifications to Known Problems heading in README

README.md

@@ -7,27 +7,30 @@ Don't feel obligated - my goal is to provide support... and to get peer reviewed
 
 Donations will go towards getting CPA validation of the calculations I'm using and answering [questions needing professional expertise](https://github.com/hickeng/financial/issues?q=is%3Aopen+is%3Aissue+label%3Acpa). I'll try to keep those issues curated such that the description is sufficiently clear and coherent to be passed directly to a CPA, but it'll be best effort. If there's questions you want answered that aren't addressed in the README and in that labelled set, please open an issue with the `cpa` label.
 
-# Known Problems
+# Known Tax Problems After Merger
 
 The problems we as VMW holders know of are collected [here](problems.md), along with groups impacted, and impact assment. All are works in progress:
 * $0 cost basis and incorrect adjustment in eTrade Supplement
    * the cascade consequences of this single issue account for the bulk of this repo
 * incorrect code ‘N’ in Form 8949 generated by TurboTax
 * treatment of proceeds as dividends
-   * substantially impacting non-US residents  
+   * substantially impacting non-US residents
 * fractional share sold at incorrect price
 * ... if you know of others, please open an issue or pull request
 
 
+
 # Install
 
-To just use the sheet directly from Google, go [here](https://docs.google.com/spreadsheets/d/1BhHIC7fdozrP8zKrc79gNPdW9p9iZX8iypyUdZoPv10/edit?usp=sharing), `File->Make a copy` then you can start entering data. If you want to use the binary from the repo, instructions are below.
+To just use the sheet directly from Google, go [here](https://docs.google.com/spreadsheets/d/1P6XHoQT0DEUJN7wosmJfDXBziSoDh5AaLgWt5YbOJ1M/edit?usp=sharing), `File->Make a copy` then you can start entering data. If you want to use the binary from the repo, instructions are below.
+
+User documentation is [here](usage.md).
 
 Install is more "import", but there's some fixup required because of a Sheets bug I haven't got a workaround for as yet.
 
-There's [a binary sheet](https://github.com/hickeng/financial/releases/download/v0.1.3/VMW_to_AVGO_ESPP_and_RSU-v0.1.3-github.xlsx) attached to the releases, suitable for import into Google Sheets.
+There's [a binary sheet](https://github.com/hickeng/financial/releases/download/v0.1.3/VMW_to_AVGO_ESPP_and_RSU-v0.1.4-github.xlsx) attached to the releases, suitable for import into Google Sheets.
 
-1. Download [the latest sheet](https://github.com/hickeng/financial/releases/download/v0.1.2/VMW_to_AVGO_ESPP_and_RSU-v0.1.3-github.xlsx)
+1. Download [the latest sheet](https://github.com/hickeng/financial/releases/download/v0.1.2/VMW_to_AVGO_ESPP_and_RSU-v0.1.4-github.xlsx)
 1. Create a new Google Sheet - [open this in new window](https://docs.google.com/spreadsheets/u/0/create?usp=sheets_home&ths=true)
 1. Go to File->Import->Upload->Browse - this will open a system file selection box. Select the downloaded sheet.
 1. Choose `Replace Spreadsheet`, and select `Import data`
@@ -43,7 +46,7 @@ There's [a binary sheet](https://github.com/hickeng/financial/releases/download/
    1. Either reload the spreadsheet, or run the `common.gs:onOpen` function using the AppScript UI
    1. Menu `Custom Functions->All balance` to trigger auth prompts
    1. Accept the authorization prompts - like self-signed website certs, you need to look at the small links below the main warning and text to proceed.
-1. Run the `Custom Functions->Optimize per-lot (avgo basis)` function - you'll be    
+1. Run the `Custom Functions->Optimize per-lot (avgo basis)` function - you'll be
    1. This sets the preference for each lot to `cash` or `shares` and you'll see the impact if choosing `manual per-lot ratio` in the Tweaks.
    1. If you want to make changes to the sheet, then export those changes for a PR, use the `Custom Functions->Export Workbook (Censored)`. This will write json to a Google Drive location and is the mechanism I use to construct the json [in the repo](worksheet/). These are intended for easy visual review of diffs. Well, easy compared to doing it as a spreadsheet.
 
@@ -53,6 +56,22 @@ There's [a binary sheet](https://github.com/hickeng/financial/releases/download/
 
 Using github project for planning - see [Timeline](https://github.com/users/hickeng/projects/2/views/2)
 
+## [v0.1.4](https://github.com/hickeng/financial/releases/tag/v0.1.4) - 2024-02-28
+
+Gets the basics of Form8949 / cost-basis entry for TurboTax in place, adding Form 8949 sections in Summary and RSU/ESPP datasheets.
+
+Additionally:
+* fixed up Turbotax 1099-B import using the sheet Form8949 as test.
+* various column renames for consistency, precision, and clarity.
+* added Close value for AVGO FMV and noted where it's stated it's acceptable (costbasis.com)
+* added ratio option for "pure" ratio from eTrade transaction log to see where that value has been used by eTrade.
+* add section for import of 1099-B values - currently an unused placeholder for pending import
+
+
+## [v0.1.3](https://github.com/hickeng/financial/releases/tag/v0.1.3) - 2024-02-28
+
+Fixes use of hardcoded test values in the per-lot optimizer logic which would have meant almost no-one trying it would have got a valid final ratio of stocks/cash.
+
 ## [v0.1.3](https://github.com/hickeng/financial/releases/tag/v0.1.2) - 2024-02-28
 
 Fixes use of hardcoded test values in the per-lot optimizer logic which would have meant almost no-one trying it would have got a valid final ratio of stocks/cash.
@@ -64,7 +83,8 @@ Refines the per-lot treatment option and adds an input for a "date of sale" for
 If you put in a date prior to 2024 then it'll roll the gains from AVGO sale into the tax estimate... but remember that's a very naive estimate and check the logic in the sheet both works for your case and is sufficient for purpose.
 
 The Tweak is found as a dropdown below the Fractional Share Values and contains dates of interest:
-* last year - this let's you see a tax estimation 
+
+* last year - this let's you see a tax estimation
 * today - calculate with todays date for LTG/STG and qualified/disqualified
 * a series of dates on which RSUs transition from STG to LTG
 

usage.md

@@ -0,0 +1,128 @@
+# Sheet User Instructions
+
+User documentation for the worksheet. This aims to be a hand-held step-by-step for how to gather the necessary documents, extract the information from them, and add it into the worksheet, chose any optional values, and then understand the result.
+
+For how to access the worksheet, see [the readme install section](https://github.com/hickeng/financial?tab=readme-ov-file#install)
+
+# Inputs
+
+This section is about getting all of the input data needed. Once gathered, you should back this up and keep it in case of future reference.
+
+## Gathering documents from eTrade
+
+There's various documents we need to export from eTrade.
+
+### eTrade Stock Plan Confirmations
+
+Gather the ESPP purchase confirmation, and RSU release confirmation documents for every lot for which you still own any shares from [the trade confirmations page](https://us.etrade.com/etx/sp/stockplan#/myAccount/stockPlanConfirmations). I don't know a better way than selecting each year in turn and clicking on the download links. If anyone finds a way to batch this, please let me know.
+
+![etrade trade confirmations download page with relevant areas highlighted](assets/etrade-confirmations-highlighted.png)
+
+Keep these for your records and back them up somewhere. They are THE definitive input into the entire process. Everything else can be reconstructed if you have these.
+
+If you sold AVGO post-merger in 2023, you'll likely need to use the tradesdownload.csv to populate the worksheet `Share amounts from eTrade` column
+
+
+### eTrade transaction log
+
+Use [the eTrade transaction log](https://us.etrade.com/e/t/accounts/txnhistory) (filter for entries relating to acquisition, propably between 2023-11-21 and 2023-12-09) to retrieve:
+* VMW shares converted to AVGO (green)
+* VMW shares exchanged for cash (blue)
+* total cash consideration recieved (dark red)
+* total AVGO received (red)
+* fractional AVGO sale price (orange)
+
+![Transaction log annotated with values to enter into sheet](assets/etrade-transaction-log-annotated.png)
+
+
+These values should be entered into the worksheet Input section on the `Summary` sheet. The VMW shares exchange for XXX are used to determine the specific conversion ratio that applied to you, which is used to calculate the per-lot quantities for cash and AVGO.
+
+The other values are used for validation as, with just the ratio and the number of shares for each lot, we expect the numbers to match up.
+
+![Colour coded Input section for worksheet](assets/sheet-summary-colour-coded-inputs.png)
+
+
+### eTrade per-lot AVGO quantities
+
+Go to etrade `Stock Plan->My Account->Benefit History` and look at the `OSPS` section:
+* for each lot, take the `Acquired Qty.` (orange) and add it into the worksheet (details below)
+* the `Total Acquired Qty.` (red) should match the number of AVGO you received in the transaction log and entered into
+
+![screenshot showing where to find quantities of AVGO after conversion ](assets/etrade-benefit-history-osps-highlighted.png)
+
+For each lot I see it bracketed with a pair of 0 qty lots. I _presume_ these come from the various holding company transitions that occurred as part of the conversion from `VMW->Holding1->Holding2->AVGO`... regardless I've ignored them.
+
+Enter these received quantities into the `Share amounts from eTrade` column in ESPP and RSU sheets. Be sure to match them up to the appropriate row in the sheet if using the sheet to save these values using the `Purchase Date`.
+
+If you had a fractional share, you'll be adjusting one of these values to add it back later, once the lot it came from has been determined.
+
+![screenshot of the ESPP sheet with shares from etrade highlighted](assets/sheet-espp-shares-from-etrade-highlight.png)
+
+)
+
+
+### eTrade 1099-B & Supplement
+
+We need to get per-lot details from the eTrade 1099-B document for 2023. For completeness you'll want the Supplement and the CSV export of your trades for 2023 tax year. If you sold VMW pre-acquisition, or AVGO post-acquisition _I expect_ them to show up in the csv, but cannot confirm personally. Keep these for your records.
+
+These documents can be found in the [eTrade Tax Center](https://us.etrade.com/etx/pxy/tax-center?resource=stock-plan).
+![eTrade tax center screenshot with relevant links highlighted](assets/etrade-tax-center-highlighted.png)
+
+
+It will contain some summary information that we don't need. What we need is the per-lot details found in `PROCEEDS FROM BROKER AND BARTER EXCHANGE TRANSACTIONS`
+![Section header](assets/1099-b-section-header.png)
+
+Within there, there may be multiple different subsections. We only care about these groupings because it makes it easier to figure out whether it's an ESPP or RSU lot:
+* `Short Term - Noncovered Securities` - RSU from 2023
+* `Long Term - Noncovered Securities` - RSU from pre-2023
+* `Long Term - Covered Securities` - ESPP (the final ESPP lot was 2022 so they'll all be here)
+
+Each of those sections has the following fields:
+![Detail headings](assets/1099-b-detail-headings.png)
+
+We're only interested in VMW shares and only lots held over the merger. So:
+* `Description Box 1a` is `VMWARE INC CLASS A`
+* `DATE SOLD (Box 1c)` is `11/24/23`
+
+For these lots I expect all of the dollar value fields to be `$0.00` except for `PROCEEDS (Box 1d)` and `GAIN(LOSS) AMOUNT`. If you've got values in any other column you'll need to understand why. Upvote [this tracking issue](https://github.com/hickeng/financial/issues/57) to flag the fact you're in this situation and the community can help figure out what it means.
+
+For each of these lots you'll enter the values for some fields into the sheet. At the bottom of the 1099-B you will also have a `Total Reportable Amounts` section
+
+
+## ESPP
+
+
+
+
+## RSU
+
+### eTrade 1099-B
+
+## Income & Taxes
+
+* 2022 1040
+* 2023 W2
+* Estimated Payments
+* Deductions & Filing Status
+
+## Sale of AVGO in 2023 post-merger
+
+
+
+# Outputs
+
+## Merger details
+
+### 2023 Captial Gain & Cash Consideration
+
+### Future Captial Gain
+
+
+# Estimated Tax
+
+
+# Custom Functions
+
+## Export
+
+## Optimizer

worksheet/common.gs

@@ -9,10 +9,12 @@ function onOpen() {
     .addItem("Export Workbook (Censored)", "serializeCensored")
     .addItem("Export Workbook (Debug)", "serializeDebug")
     .addSeparator()
+
     .addItem("Export Active Sheet (with Data)", "serializeActiveStandard")
     .addItem("Export Active Sheet(Censored)", "serializeActiveCensored")
     .addItem("Export Active Sheet (Debug)", "serializeActiveDebug")
     .addSeparator()
+
     .addItem("Optimize per-lot (vmw basis)", "optimizeVMW")
     .addItem("Optimize per-lot (avgo basis)", "optimizeAVGO")
 
@@ -30,5 +32,5 @@ function onOpen() {
 function shortDate(input) {
     var date = new Date(input)
     var isoString = Utilities.formatDate(date, "UTC", "yyy-MM-dd")
-    return isoString.split("T")[0]  
+    return isoString.split("T")[0]
 }

worksheet/config.gs

@@ -9,6 +9,8 @@ const overrideStartIndex = 0
 
 var useFutureBasisForOptimization = true
 var useSyntheticBasisForOptimization = true
+// When set to true, all lots that would realize an actual loss if straight cash are kept as pro-rata
+var forceLossLotsToBalance = false
 
 // Merge processing turned out to be insanely slow.
 // Almost 60s added just for the cells in Summary, with the bulk of that spent
@@ -52,6 +54,7 @@ const datasheetSpecificHeadingRow = 3 // 0-indexed
 const datasheetDataStartRow = 6 // 0-indexed
 
 // Reference sheet
+const vmwCashPriceA1Notation = "B3"
 const derivedStockRatioCellA1Notation = "B5"
 const balanceRatioA1Notation = "E7"
 // TODO: don't just hardcode to max

worksheet/export.gs

@@ -1,3 +1,4 @@
+
 /////////////////////////
 // Serialization
 
@@ -428,10 +429,11 @@ function cellColourMapping(code) {
         type: "in_ref",
         sensitive: true,
       }
-    
+
     case "#a2c4c9":
-      // data validation modified colour
+    // data validation modified colour
     case "#d0e0e3":
+    case "#bbc8cb": // alternating colours formatting
       return {
         type: "out_now",
         sensitive: false,
@@ -479,6 +481,7 @@ function cellFormatMapping(formatString) {
       }
 
     case "#,##0.00;(#,##0.00)":
+    case "[$$]#,##0.00":
       return {
         type: "financial",
         formatString: formatString,
@@ -554,6 +557,7 @@ function cellFormatMapping(formatString) {
 
     case "yyyy\"-\"mm\"-\"dd":
     case "yyyy-mm-dd":
+    case "mm\"/\"dd\"/\"yy":
       return {
         type: "iso-date",
         formatString: formatString,