Tax Practice AI - Roadmap¶
Future features, AI optimization, and post-V1 planning
Related Documents¶
| Document | Purpose |
|---|---|
| backlog.md | Active priorities |
| COMPLETED.md | Completed items |
| TECH_DEBT.md | Technical debt tracking |
| DESIGN_DECISIONS.md | Architecture decisions |
| index.md | Master navigation |
Roadmap Overview¶
| Phase | Target | Focus |
|---|---|---|
| V1 | Jan 2025 | Back-office AI companion (Tax Season 2025) |
| V1.1 | Q2 2025 | P1 security/compliance, data quality features |
| V1.2 | Q3 2025 | Client portal, advanced features |
| V2 | 2026 | Full client-facing platform |
AI Chat Backlog (S13 Future)¶
Items deferred from Sequence 13 implementation:
| ID | Feature | Priority | Notes |
|---|---|---|---|
| S13-005 | Chat Integration Tests | P1 | Pending |
| S13-006 | Client Portal Chat | P2 | Post-V1.1 |
| S13-007 | WebSocket Streaming | P2 | Real-time responses |
| S13-008 | Cross-Client Queries | P3 | After security/cost analysis |
| S13-009 | Opus Escalation | P2 | "Ask the Expert" button |
Expedited Analysis Pricing (PRICE-001)¶
Status: Backlog Priority: P1 (Revenue Feature) Target: Post-V1 Launch Meeting Reference: 2024-12-29 call item #8
Business Model¶
Tiered document analysis with freemium expedited processing:
V1 Requirement (per 2024-12-29 meeting): Need clearly labeled "Process Now" button for when staff is on the phone with a client and needs immediate analysis rather than waiting for batch.
| Processing Tier | Timing | Cost |
|---|---|---|
| Batch (Default) | Overnight | Included |
| Expedited | Immediate (~30 sec/doc) | Free quota, then $1.50/doc |
Freemium Model: - All clients receive 25 free expedited analyses per month - After quota exhausted: $1.50 per document OR wait for overnight batch - Counter resets on 1st of each month
User Experience¶
Document Upload Flow: 1. Documents uploaded show status: "Pending Analysis" 2. Banner displays: "3 documents pending. Overnight batch included, or analyze now." 3. Show quota: "15 of 25 expedited analyses remaining this month" 4. When quota exhausted, button changes to "Analyze Now ($1.50)" or "Queue for Overnight"
Implementation¶
Database Changes:
- Add expedited_analyses_used counter to client/account table (resets monthly)
- Add expedited_analyses_limit field (default: 25)
- Add analysis_status enum to documents: pending → queued → processing → complete
Files to Create:
- src/domain/analysis_quota.py
- src/repositories/analysis_quota_repository.py
- src/workflows/document_analysis/batch_processor.py
- dags/overnight_analysis_dag.py
Margin Analysis¶
At current AI costs (~$0.05/doc for analysis): - Expedited fee: $1.50/doc - Cost: $0.05/doc - Margin: 97%
Free quota (25/month) costs ~$1.25/month per client - acceptable customer acquisition cost.
Duplicate Document Detection (DUP-001)¶
Status: Implemented (2024-12-27) Priority: P2 (Data Quality)
Detect duplicates on upload using file hash. Same-client duplicates blocked; cross-client matches warn user (likely wrong client selected).
Name Mismatch Detection (DUP-002)¶
Status: Backlog Priority: P3 (Data Quality) Target: V1.2
Problem¶
Document uploaded to wrong client - e.g., W-2 for "John Smith" uploaded to client "Jane Doe".
Solution¶
Post-processing check after document extraction: 1. Extract name from document metadata (W-2, 1099, etc.) 2. Fuzzy match against client name 3. If mismatch, flag for review
Considerations¶
- Requires OCR/extraction to complete first
- Fuzzy matching needed ("John Smith" vs "John A. Smith")
- Joint returns - both spouse names are valid
- Some docs have no name (receipts, bank statements)
Multi-Document PDF Splitting (DOC-003)¶
Status: Backlog Priority: P2 (Workflow Enhancement) Target: V1.1 Added: 2024-12-30 Meeting Reference: 2024-12-29 call item #14
Problem¶
During peak periods, staff scan multiple documents into a single PDF to save time. System needs to automatically split these into individual documents for proper classification and tracking.
Solution¶
AI-powered document boundary detection: 1. Detect document boundaries within multi-page PDF 2. Split into individual documents 3. Classify each resulting document 4. Allow manual correction of splits
Notes (per 2024-12-29 meeting)¶
- Staff prefer individual scans normally
- Batch-and-split needed during peak periods for efficiency
- Must support manual override if AI splits incorrectly
Multi-Account Document Recognition (per 2024-12-30 feedback)¶
Beyond physical document splitting, extraction must also handle consolidated statements (e.g., Merrill Lynch) that contain multiple accounts in a single document: - Recognize account boundaries within a single document - Extract each account's data separately - Associate extracted data with correct account identifiers - Example: One brokerage PDF with 3 accounts → extract 3 separate data sets
Concurrent Edit Handling (CONC-001)¶
Status: Planning Complete Priority: P2 (Data Integrity) Target: V1.1 Plan: docs/plans/OPTIMISTIC_LOCKING.md
Add optimistic locking to prevent silent data loss when two users edit same record.
Effort Estimate: 8-10 hours
Field-Level Merging (CONC-002)¶
Status: Planned Priority: P3 (UX Enhancement) Target: V1.2 Depends on: CONC-001
Auto-merge non-overlapping field changes. Only show conflict dialog for same-field edits.
Effort Estimate: 4-6 hours
Special Conflict Scenarios (CONC-003)¶
Status: Planned Priority: P3 (Data Integrity) Target: V1.2 Depends on: CONC-001
Handle edge cases: delete vs update, status race, assignment collision, bulk vs single.
Effort Estimate: 6-8 hours
Client Actions (UI-001, UI-002)¶
UI-001: Send Portal Invite¶
Target: V1.1 Send invitation email to client with portal access link.
UI-002: Create Engagement Letter¶
Target: V1.1 Generate engagement letter from template, pre-filled with client info.
AI-Support Ticketing System (SUP-001)¶
Status: Backlog Priority: P2 (Client Experience) Target: V1.2
Features¶
- Ticket intake (portal, email, phone)
- AI triage and auto-classification
- AI draft responses for common questions
- Staff review and edit before sending
- Resolution tracking and satisfaction scores
Ticket Types¶
- Document request
- Status inquiry
- Tax question
- Technical support
- Billing inquiry
- Appointment request
Effort Estimate: 44-58 hours
Bookkeeping Module (PHASE-BKP)¶
Status: Requirements Drafted Priority: Post-MVP Requirements: bookkeeping_requirements.md
Phased Implementation¶
- Phase 1: Bank statement upload, AI categorization, QuickBooks export
- Phase 2: Reconciliation, recurring transaction detection
- Phase 3: Full bookkeeping (chart of accounts, P&L, Balance Sheet, two-way sync)
Pending Client Input¶
- Service level (tax-ready categorization vs full bookkeeping)
- Target clients (business entities only vs all clients)
- Pricing model (monthly retainer vs per-transaction)
AI Cost Optimization¶
Critical for SaaS business model. See COST_DETAIL.md for full analysis.
OPT-001: Metadata Caching¶
Status: Complete (2025-12-28) Priority: P0 (Core to SaaS margins) Estimated Impact: 60-75% token reduction, $0.24/return savings Meeting Reference: 2024-12-29 call item #13
Extract once, cache as markdown, reference forever. Per-document and per-return metadata files in S3.
Enhancement (per 2024-12-29 meeting): Also store document metadata in database for querying, not just S3 MD files.
OPT-002: Batch API Default¶
Status: Not Started Priority: P0 (Core to SaaS margins) Estimated Impact: 50-60% cheaper on batch-eligible tasks
Default to overnight batch processing with opt-in for real-time. Queue document processing via Airflow.
Batch-eligible tasks: - Document classification and extraction - Prior year comparison - Missing document detection - Worksheet generation - Rejection analysis - Tax reminders
OPT-003: Model Delegation Strategy¶
Status: Not Started Priority: P1 Estimated Impact: 38% AI cost reduction
Use cheapest model capable for each task:
SONNET (Orchestrator) → HAIKU (60% - extraction)
→ SONNET (35% - analysis)
→ OPUS (5% - expert review)
OPT-004: Combined Optimization Target¶
Priority: P0 Target: $0.12/return AI cost (vs $0.40 baseline)
Combined impact: 1. Batch processing (80%): $0.40 → $0.28 2. Metadata caching (75%): $0.28 → $0.12 3. Model delegation: Further optimization within each tier
At scale (10,000 returns): - Baseline: $4,000/year AI cost - Optimized: $1,200/year AI cost - Annual savings: $2,800
OPT-005: Prompt Compression¶
Status: Not Started Priority: P2 (Quick Win) Estimated Impact: 10-20% additional token reduction
Use LLMLingua to compress static prompts and tax code references.
OPT-006: Output Token Limits¶
Status: Not Started Priority: P2 (Quick Win) Estimated Impact: 5-15% output token reduction
Force shorter, structured responses for extraction/classification tasks.
OPT-007: Semantic Caching¶
Status: Not Started Priority: P2 Estimated Impact: 15-30% reduction on repeated queries
Cache responses by meaning, not exact match. Return cached answer for semantically similar queries.
OPT-008: RAG Optimization¶
Status: Not Started Priority: P2 Estimated Impact: 20-30% context token reduction
Retrieve only relevant document sections based on the question.
OPT-009: Confidence-Based Escalation¶
Status: Not Started Priority: P3 Estimated Impact: 10-20% model cost reduction
Let Haiku attempt everything first, escalate dynamically based on confidence.
OPT-010: Fine-Tuning (Future)¶
Status: Not Started Priority: P4 (Volume-dependent) Estimated Impact: 30-50% cost reduction on fine-tuned tasks
Train smaller models on repetitive, domain-specific tasks after 6+ months production data.
OPT-011: Knowledge Distillation (Future)¶
Status: Not Started Priority: P4 (Volume-dependent) Estimated Impact: 50-85% cost reduction on distilled tasks
Use Opus to generate training data, teach Haiku to mimic Opus responses.
Tax Reference System¶
Tax code reference system created 2024-12-27. Serves both Claude Code /tax skill and Bedrock chatbot (RAG).
TAX-REF-001: Senior Tax Administrator Role (RBAC)¶
Status: Backlog Priority: P2 Dependency: RBAC system implementation
Add role for tax staff to direct tax reference updates via Claude conversation.
TAX-REF-002: Firm-Specific Tax Skills/Overrides¶
Status: Backlog Priority: P2 Dependency: TAX-REF-001
Allow firms to customize tax reference with firm-specific guidance.
TAX-REF-003: Bedrock Knowledge Base Integration¶
Status: Backlog Priority: P1 Dependency: BedrockService implementation
Index tax reference files into Bedrock Knowledge Base for RAG.
TAX-REF-004: Per-Client Tax Context Metadata¶
Status: Backlog Priority: P1 Dependency: AI Analysis workflow, TAX-REF-003
Auto-generated per-client tax context that primes the chatbot with relevant jurisdictions and skills.
File Structure:
s3://tax-practice-documents/{client_id}/{return_year}/
├── tax_context.md # Current state (~50 lines, always loaded)
├── tax_context_pending.md # Chatbot-flagged updates awaiting review
└── tax_context_history.md # Full changelog/audit trail
Effort Estimate: 33-45 hours of human review time
Future Sequences (S14-S18)¶
| Sequence | Description | Status |
|---|---|---|
| S14 | Extensions | Planned |
| S15 | Year-End Processing | Planned |
| S16 | Multi-State | Planned |
| S17 | Business Entities | Planned |
| S18 | Advanced Reporting | Planned |
See USER_STORIES.md for detailed story breakdowns.
Last updated: 2025-12-30