---
name: us-cpa
description: Use when answering U.S. federal individual tax questions, preparing a federal Form 1040 return package, or reviewing a draft/completed federal individual return.
---

# US CPA

`us-cpa` is a Python-first federal individual tax workflow skill. The CLI is the canonical engine. Use the skill to classify the request, gather missing inputs, and invoke the CLI.

## Modes

- `question`
  - one-off federal tax question
  - case folder optional
- `prepare`
  - new or existing return-preparation case
  - case folder required
- `review`
  - new or existing return-review case
  - case folder required

## Agent Workflow

1. Determine whether the request is:
   - question-only
   - a new preparation/review case
   - work on an existing case
2. If the request is `prepare` or `review` and no case folder is supplied:
   - ask whether to create a new case
   - ask where to store it
3. Use the bundled CLI:

```bash
skills/us-cpa/scripts/us-cpa question --question "What is the standard deduction?" --tax-year 2025
skills/us-cpa/scripts/us-cpa question --question "What is the standard deduction?" --tax-year 2025 --style memo --format markdown
skills/us-cpa/scripts/us-cpa prepare --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
skills/us-cpa/scripts/us-cpa review --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 --style memo --format markdown
skills/us-cpa/scripts/us-cpa extract-docs --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe --create-case --case-label "Jane Doe" --facts-json ./facts.json
```

4. For `question` mode, do not mechanically repeat the CLI fallback text.
   - If the CLI returns `analysis.excerpts` with `primaryLawRequired: false`, answer the user directly from those IRS excerpts in your own words.
   - Cite the specific IRS authorities returned by the CLI.
   - Only tell the user the question needs deeper legal research when the CLI returns `primaryLawRequired: true` and no relevant IRS excerpts were found.

When OpenClaw is using the installed workspace copy, the entrypoint is:

```bash
~/.openclaw/workspace/skills/us-cpa/scripts/us-cpa --help
```

## Rules

- federal individual returns only in v1
- IRS materials first; escalate to primary law only when needed
- stop on conflicting facts and ask the user to resolve the issue before continuing
- official IRS PDFs are the target compiled-form artifacts
- deterministic field-fill is the preferred render path when the official PDF exposes usable fields
- overlay-rendered forms are the fallback and must be flagged for human review

## Output

- JSON by default
- markdown output available with `--format markdown`
- `question` supports `--style conversation|memo`
- `fetch-year` downloads the bootstrap IRS form/instruction corpus into `~/.cache/us-cpa` by default
- override the cache root with `US_CPA_CACHE_DIR` when you need an isolated run or fixture generation
- `extract-docs` creates or opens a case, registers documents, stores facts, extracts machine-usable facts from JSON/text/PDF sources where possible, and stops with a structured issue if facts conflict
- `question` now searches the downloaded IRS corpus for relevant authorities and excerpts before escalating to primary-law research
- rendered form artifacts prefer fillable-field output when possible and otherwise fall back to overlay output
- `prepare` computes the current supported federal 1040 package, preserves fact provenance in the normalized return, and writes normalized return/artifact/report files into the case directory
- `export-efile-ready` writes a draft transmission-ready payload without transmitting anything
- `review` recomputes the return from case facts, checks artifacts, flags source-fact mismatches and likely omissions, and returns findings-first output in conversation or memo style

For operator details, limitations, and the planned case structure, see `docs/us-cpa.md`.
