tax-doc-scan

Files (2)

• SKILL.md
• tax-doc-types.md · references/

SKILL.md (first lines)

# /tax-doc-scan — Tax Document Visual Inspection & Classification

Scan, visually inspect, and classify every tax document across Gmail, Drive, and Paperless.
The cardinal rule: **never trust filenames** — every page must be visually inspected and classified
from its actual content.

## MCP Tool Map

| Task | Tool | Notes |
|------|------|-------|
| Search Gmail for tax attachments | `google-workspace-personal-ro.search_gmail_messages` | Date-range + keyword queries |
| Search Drive for tax folders | `google-workspace-personal-ro.search_drive_files` | Folder and filename scans |
| Download Drive file | `google-workspace-personal-ro.get_drive_file_content` | Retrieve for visual inspection |
| Search Paperless documents | `paperless.search_documents` | Find untagged or recently added docs |
| Get Paperless document | `paperless.get_document` | Metadata and content retrieval |
| Download Paperless document | `paperless.download_document` | Full document for page-level inspection |
| Upload to Paperless | `paperless.post_document` | Ingest with metadata |
| Update Paperless metadata | `paperless.update_document` | Correct tags, title, correspondent |
| List Paperless tags | `paperless.list_tags` | Resolve tag IDs at runtime |

## Workflow

### Phase 1: Discovery

Scan all document sources for tax-season candidates.

1. **Gmail** — search for tax-season attachments:
   - Query: `W-2 OR 1099 OR K-1 OR 1098 OR 1095 OR 5498 OR "tax document" OR "tax form"` scoped to the relevant date range (typically Jan 1 through Apr 15 of the filing year).
   - Extract: sender, subject, date, attachment filenames.

2. **Drive** — search for tax folders and loose documents:
   - Look in known tax folders (e.g., `Tax/TY 2025/`) and run keyword queries.
   - Extract: filename, path, modified date, sharing status.

3. **Paperless** — search for recently added untagged documents:
   - Filter to documents added in the last 90 days without a `tax-relevant` tag or without any tags at all.
   - Check for documents that may have been auto-ingested but not classified.

4. **Build candidate list** with columns: source (Gmail/Drive/Paperless), filename, date received/modified, sender or folder path, preliminary guess from filename.

### Phase 2: Visual Inspection

For every candidate document — no exceptions:

1. Download or retrieve the full document content.
2. Inspect **every page** of every document. Multi-page PDFs may contain multiple distinct forms, cover letters, or state vs federal copies.
3. Identify the actual document type from content (form headers, OMB numbers, payer/employer blocks, tax year, recipient name). See `references/tax-doc-types.md` for visual identification hints per form type.

### Phase 3: Classification

Classify each inspected document using `references/tax-doc-types.md`.

For each document, extract:
- **Document type**: W-2, 1099-INT, 1099-DIV, K-1, 1098, etc.
- **Tax year**: as printed on the form.
- **Payer/employer**: name and EIN.
- **Recipient**: name and SSN last 4 only (never log or store full SSN/TIN).
- **Key amounts**: gross wages, interest income, dividends, capital gains, etc. — the primary box values.

Flag discrepancies:
- Filename says "1099" but content is actually a W-2.
- Email subject says "2024 Tax Documents" but form shows TY 2025.
- Recipient name does not match any household member.
- Same form appears in multiple sources (Gmail attachment + Drive copy).

### Phase 4: Filing

File each classified document to Paperless following the conventions in `references/tax-doc-types.md` (Filing Conventions section) and the `document-filing` skill taxonomy.

1. Apply title format, tags, correspondent, and document type per the reference file conventions.
2. Set tax year custom field if the Paperless instance supports it.
3. **Deduplication** — before uploading, search Paperless for existing copies (match on form type + payer + tax year). If a match exists, update metadata rather than re-uploading.

### Phase 5: Completeness Report

Generate a filing-season completeness checklist.

1. **Expected documents** — based on prior year sources:
   - List every employer, bank, brokerage, partnership, and institution that issued a tax document last year.
   - For each, note the expected form type(s).

2. **Received vs expected**:

   ```
   | Source | Form | TY | Status | Paperless ID |
   |--------|------|----|--------|--------------|
   | Acme Corp | W-2 | 2025 | Received | #1234 |
   | Chase Bank | 1099-INT | 2025 | Received | #1235 |
   | Fidelity | 1099-DIV | 2025 | MISSING | — |
   ```

3. **Flag gaps**: "Missing 1099-DIV from Fidelity (received last year on 2025-02-12)."

4. **Flag duplicates**: same form type from same source found in multiple locations.

5. **Recommended follow-up**: contact payer, check online portal, wait for late mailing.

## Output Contract

Every run must return:

| Field | Type | Description |
|-------|------|-------------|
| `as_of` | ISO 8601 timestamp | When the scan was performed |
| `documents_scanned` | integer | Total candidate documents inspected |
| `classification_results` | list | Each entry: `{source, filename, classified_type, tax_year, payer, recipient_last4, key_amounts, paperless_doc_id}` |
| `discrepancies` | list | Filename-vs-content mismatches, year mismatches, unknown recipients |
| `completeness_checklist` | list | Expected vs received per source and form type |
| `filing_results` | list | Paperless upload/update confirmations with document IDs |
| `gaps` | list | Missing documents with prior-year context |
| `recommended_actions` | list | Follow-up steps for gaps and discrepancies |

## Critical Rules

1. **Never trust filenames** — always inspect the actual document content. A file named `1099.pdf` might contain a W-2, a cover letter, or a completely unrelated document.
2. **Every page matters** — multi-page PDFs may contain multiple distinct forms. Inspect each page individually and classify separately if needed.
3. **Privacy** — only log the last 4 digits of SSN/TIN. Never store, display, or transmit full Social Security Numbers or Taxpayer Identification Numbers.
4. **Provenance** — track and report the source system (Gmail, Drive, or Paperless) and source locator (message ID, file ID, document ID) for every document.
5. **Idempotency** — re-running the scan should not create duplicate Paperless entries. Always check for existing documents before uploading.

From hvkshetry/StewardOS, MIT.

More from hvkshetry/StewardOS