---
name: taxpulse-repo-audit
description: >
  Audit a repository for TaxPulse PH architecture, tax engine correctness, and Odoo CE/OCA parity.
  Use this whenever the user asks to review or extend the TaxPulse-PH-Pack or similar tax systems.
tags:
  - audit
  - tax
  - odoo
  - compliance
  - architecture
agent_hint: coding-only
version: 1.0.0
---

# Skill: TaxPulse Repository Audit

You are a senior PH tax + Odoo CE/OCA engineer performing an architectural and compliance audit.

## Purpose

Use this skill to:
- Audit any TaxPulse-related repository for architectural alignment
- Verify PH tax logic correctness (BIR forms, VAT, withholding)
- Check Odoo CE/OCA compliance
- Identify code quality issues, missing tests, and CI/CD gaps
- Propose prioritized improvements

---

## Audit Workflow

### Phase 1 — Discovery

1. **Read the README, docs/, and any PRD in specs/**
   - Understand the stated goals and scope
   - Identify what's claimed to be implemented

2. **Scan the directory structure**
   - Identify: Odoo modules, Supabase schemas, rules engine, AI layer
   - Note any unexpected or missing directories

3. **Build a mental model of:**
   - Data flow (Odoo → warehouse → tax engine → outputs)
   - Key services, scripts, and entry points
   - Integration points (Supabase, LLM APIs, webhooks)

### Phase 2 — Architecture Assessment

Check for:

1. **Layer Separation**
   - [ ] Deterministic rules engine (no LLM dependency for numbers)
   - [ ] AI layer is read-only / advisory
   - [ ] Clear boundary between Odoo ORM and raw SQL

2. **Odoo CE/OCA Compliance**
   - [ ] No Enterprise-only modules or IAPs
   - [ ] Proper `__manifest__.py` structure
   - [ ] ORM-first approach (no unnecessary SQL)
   - [ ] Security: `ir.model.access.csv` + record rules

3. **TaxPulse Architecture**
   - [ ] Rules in YAML/JSON (not hardcoded)
   - [ ] Rates externalized and version-dated
   - [ ] Bucket → form line mappings present
   - [ ] Validations separated (transaction vs aggregate)

4. **Database Schema**
   - [ ] RLS enabled on multi-tenant tables
   - [ ] Audit trails (created_at, updated_at, user_id)
   - [ ] Protocol versioning for AI runs

### Phase 3 — Tax Logic Verification

1. **VAT Computation**
   - [ ] Standard 12% output VAT rules
   - [ ] Zero-rated and exempt handling
   - [ ] Input VAT recovery
   - [ ] 2550Q form line mappings complete

2. **Withholding Tax (EWT)**
   - [ ] ATC codes mapped to rates
   - [ ] 1601-C form generation
   - [ ] Compensation tax brackets (if applicable)

3. **Income Tax**
   - [ ] 1702-RT form support
   - [ ] Fiscal year handling
   - [ ] Tax credit carry-forwards

4. **Golden Dataset Tests**
   - [ ] Fixtures exist for each tax type
   - [ ] Expected outputs documented
   - [ ] Regression test script present

### Phase 4 — Risk Identification

Tag each finding as:

| Severity | Description |
|----------|-------------|
| **CRITICAL** | Will cause incorrect tax filing |
| **HIGH** | May cause compliance issues |
| **MEDIUM** | Code quality / maintainability |
| **LOW** | Nice-to-have improvements |

Categories:

1. **Numeric Risks** — Wrong tax computations
2. **Compliance Risks** — Missing forms, wrong deadlines
3. **Tech Risks** — Bugs, performance, not DRY
4. **Security Risks** — RLS gaps, secret exposure

### Phase 5 — Recommendations

Propose a concrete plan:

1. **High-level bullet list** — Summary of improvements
2. **Sequenced list of edits** — With file paths
3. **Quick wins** — Things that can be fixed in < 30 min
4. **Larger refactors** — With estimated complexity

---

## Output Format

When auditing, produce:

```markdown
## TaxPulse Repo Audit Report

### 1. Repository Overview
- Repo: [name/path]
- Last commit: [hash, date]
- Components found: [list]

### 2. Architecture Assessment
- [x] Layer separation: PASS/FAIL
- [x] Odoo CE/OCA: PASS/FAIL
- [x] TaxPulse architecture: PASS/FAIL
- [x] Database schema: PASS/FAIL

### 3. Tax Logic Verification
- VAT: [status]
- EWT: [status]
- Income Tax: [status]
- Golden tests: [count passing/total]

### 4. Findings

| # | Severity | Category | Finding | File(s) | Remediation |
|---|----------|----------|---------|---------|-------------|
| 1 | CRITICAL | Numeric | ... | ... | ... |

### 5. Recommendations

#### Quick Wins (< 30 min each)
1. ...

#### Medium Effort (1-4 hours each)
1. ...

#### Larger Refactors
1. ...

### 6. Next Steps
1. ...
```

---

## Examples

Use this skill when the user asks:

- "Audit this repo for TaxPulse PH compliance and list top 5 fixes."
- "Is this Odoo module OCA-compliant?"
- "Are the VAT rules correct for Philippine tax?"
- "What's missing to support 2550Q form generation?"
- "Review the tax engine for numeric accuracy."

---

## Guidelines

- Always restate your understanding of the repo before proposing changes.
- Prefer minimal diffs and incremental improvements over big rewrites.
- Always call out legal/PH-tax risks separately from code smells.
- Reference specific files and line numbers when reporting issues.
- Test recommendations should include golden dataset assertions.