taxpulse-repo-audit
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.
When & Why to Use This Skill
The TaxPulse Repository Audit skill is a specialized tool designed for senior engineers to perform deep architectural and compliance reviews of Philippine tax software. It automates the evaluation of repositories for TaxPulse PH alignment, Odoo CE/OCA standards, and the accuracy of tax engines regarding BIR regulations. By identifying critical numeric risks and code quality issues, it ensures that tax-related software is robust, compliant, and ready for production.
Use Cases
- Philippine Tax Compliance: Verifying that tax engines correctly handle 12% VAT, Withholding Tax (EWT) codes, and Income Tax calculations according to BIR requirements.
- Odoo Module Auditing: Ensuring Odoo modules adhere to OCA (Odoo Community Association) standards, avoiding Enterprise-only dependencies and following ORM best practices.
- Architectural Integrity Checks: Assessing the separation between deterministic rules engines and AI layers to ensure financial calculations remain accurate and traceable.
- Pre-deployment Risk Assessment: Identifying critical bugs in tax form generation (e.g., 2550Q, 1601-C) and security gaps like Row-Level Security (RLS) in multi-tenant databases.
- Technical Debt Prioritization: Generating structured audit reports that categorize findings by severity (Critical to Low) and provide actionable remediation plans for developers.
| name | taxpulse-repo-audit |
|---|---|
| description | > |
| 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
Read the README, docs/, and any PRD in specs/
- Understand the stated goals and scope
- Identify what's claimed to be implemented
Scan the directory structure
- Identify: Odoo modules, Supabase schemas, rules engine, AI layer
- Note any unexpected or missing directories
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:
Layer Separation
- Deterministic rules engine (no LLM dependency for numbers)
- AI layer is read-only / advisory
- Clear boundary between Odoo ORM and raw SQL
Odoo CE/OCA Compliance
- No Enterprise-only modules or IAPs
- Proper
__manifest__.pystructure - ORM-first approach (no unnecessary SQL)
- Security:
ir.model.access.csv+ record rules
TaxPulse Architecture
- Rules in YAML/JSON (not hardcoded)
- Rates externalized and version-dated
- Bucket → form line mappings present
- Validations separated (transaction vs aggregate)
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
VAT Computation
- Standard 12% output VAT rules
- Zero-rated and exempt handling
- Input VAT recovery
- 2550Q form line mappings complete
Withholding Tax (EWT)
- ATC codes mapped to rates
- 1601-C form generation
- Compensation tax brackets (if applicable)
Income Tax
- 1702-RT form support
- Fiscal year handling
- Tax credit carry-forwards
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:
- Numeric Risks — Wrong tax computations
- Compliance Risks — Missing forms, wrong deadlines
- Tech Risks — Bugs, performance, not DRY
- Security Risks — RLS gaps, secret exposure
Phase 5 — Recommendations
Propose a concrete plan:
- High-level bullet list — Summary of improvements
- Sequenced list of edits — With file paths
- Quick wins — Things that can be fixed in < 30 min
- Larger refactors — With estimated complexity
Output Format
When auditing, produce:
## 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.