stef-openclaw-skills/docs/us-cpa.md

us-cpa

us-cpa is a Python CLI plus OpenClaw skill wrapper for U.S. federal individual tax work.

Current Milestone

Milestone 2 now adds the first tax-year corpus layer:

• deterministic cache layout under ~/.cache/us-cpa by default
• fetch-year download flow for the bootstrap IRS corpus
• source manifest with URL, hash, authority rank, and local path traceability
• authority ranking hooks for IRS materials and future primary-law escalation

Tax logic, case workflows, rendering, and review logic are still pending.

CLI Surface

skills/us-cpa/scripts/us-cpa question --question "What is the standard deduction?" --tax-year 2025
skills/us-cpa/scripts/us-cpa prepare --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa review --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa fetch-year --tax-year 2025
skills/us-cpa/scripts/us-cpa extract-docs --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa render-forms --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa export-efile-ready --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe

Tax-Year Cache

Default cache root:

~/.cache/us-cpa

Override for isolated runs:

US_CPA_CACHE_DIR=/tmp/us-cpa-cache skills/us-cpa/scripts/us-cpa fetch-year --tax-year 2025

Current fetch-year bootstrap corpus for tax year 2025 is verified against live IRS irs-prior PDFs for:

• Form 1040
• Schedules 1, 2, 3, A, B, C, D, SE, and 8812
• Form 8949
• General Form 1040 instructions and selected schedule/form instructions

Interaction Model

• question
  • stateless by default
  • optional case context
• prepare
  • requires a case directory
  • if none exists, OpenClaw should ask whether to create one and where
• review
  • requires a case directory
  • can operate on an existing or newly-created review case

Planned Case Layout

<case-dir>/
  input/
  extracted/
  return/
  output/
  reports/
  issues/
  sources/

Output Contract

• JSON by default
• markdown available with --format markdown
• question, prepare, review, extract-docs, render-forms, and export-efile-ready still emit scaffold payloads with status: "not_implemented"
• fetch-year emits a downloaded manifest location and source count

Scope Rules

• U.S. federal individual returns only in v1
• official IRS artifacts are the target output for compiled forms
• conflicting facts must stop the workflow for user resolution

Authority Ranking

Current authority classes are ranked to preserve source hierarchy:

• IRS forms
• IRS instructions
• IRS publications
• IRS FAQs
• Internal Revenue Code
• Treasury regulations
• other primary authority

Later research and review flows should consume this ranking rather than inventing their own.