Invoice Audit System - Cursor Rules

A professional-grade, fully automated invoice processing and audit system driven entirely by YAML configuration templates. This skill enables AI assistants to build, maintain, and operate a zero-manual-edit invoice validation pipeline.

Overview

This system implements a template-driven architecture where every company has its own YAML profile defining parsing rules, validation logic, and audit criteria. The AI assistant follows a structured roadmap to implement features phase-by-phase, ensuring consistent, maintainable code.

Core Principles

1. Template-Driven Architecture

**YAML is the Source of Truth**: All invoice processing logic lives in YAML configuration files in the `templates/` directory. Never hardcode company-specific logic in Python code.

**One Profile Per Company**: Each company MUST have its own YAML profile at `templates/companies/{company_key}.yaml` defining:

Invoice identification patterns

Field extraction rules (regex, positions, keywords)

Validation rules and thresholds

Audit criteria (PASS/HOLD/FAIL conditions)

2. File Structure

```

C:\llm\llm_chat_app\

├── templates/

│ └── companies/

│ ├── volta_hub.yaml

│ ├── company_two.yaml

│ └── ...

└── backend/

├── company_detector.py

├── template_parser.py

└── invoice_auditor.py

C:\all the shit\

├── VOLTA HUB ELECTRICAL TRADING CO. L.L.C\

│ ├── VH-87.pdf

│ └── ...

├── Company Two Name\

│ └── invoices...

└── ...

```

3. Processing Pipeline

1. **Detect Company**: Use `company_detector.py` to identify which company issued the invoice

2. **Load Template**: Load the corresponding YAML profile

3. **Parse Invoice**: Use `template_parser.py` with the template rules

4. **Audit**: Pass parsed data to `invoice_auditor.py` for validation

Implementation Instructions

Step 1: Understand the User's Role

The user is the project owner building a fully automated invoice audit system. Your role is to:

Implement features from the `auditfix.md` roadmap step-by-step

Never skip phases or steps

Announce each step before executing it

Stop immediately on errors and propose specific fixes (wait for approval)

Step 2: Follow the Roadmap

The `auditfix.md` file contains the implementation roadmap. When instructed to implement a phase:

1. Locate the phase number in `auditfix.md`

2. Read all steps in that phase

3. Announce: "Implementing Phase {X}: {Phase Title}"

4. For each step:

- Announce: "Step {X}.{Y}: {Step Description}"

- Execute the step

- Confirm completion before moving to next step

Step 3: Handle Special Commands

#### @create_all_company_profiles

Automated bulk profile generation:

1. Scan `C:\all the shit\` for all subdirectories

2. For each subdirectory:

- Treat folder name as `company_name`

- Find first PDF as `reference_invoice`

- Generate `company_key` (lowercase, underscores, no special chars)

- Analyze reference invoice structure

- Create `templates/companies/{company_key}.yaml`

- Populate with deduced parsing rules

3. Provide summary of all profiles created

#### @create_company_profile(company_name="{name}")

Single company profile generation:

```

@create_company_profile(company_name="VOLTA HUB ELECTRICAL TRADING CO. L.L.C")

```

1. Generate `company_key` from name (e.g., "volta_hub")

2. Locate folder: `C:\all the shit\{company_name}\`

3. Select first PDF as reference invoice

4. Analyze PDF structure:

- Identify company identifiers (name variations, tax IDs, addresses)

- Map field locations (invoice number, date, amounts, line items)

- Detect table structures

- Note calculation patterns

5. Create YAML template with sections:

```yaml

company_key: volta_hub

company_name: "VOLTA HUB ELECTRICAL TRADING CO. L.L.C"

identifiers:

- name_patterns: ["VOLTA HUB", "VH ELECTRICAL"]

- tax_id: "TRN-12345"

fields:

invoice_number:

type: regex

pattern: "Invoice #: ([A-Z0-9-]+)"

total_amount:

type: keyword

keyword: "Total Amount"

position: after

validation:

required_fields: [invoice_number, date, total]

calculations:

- check: subtotal + vat = total

audit_rules:

pass_conditions: [all_fields_present, calculations_valid]

hold_conditions: [missing_optional_field]

fail_conditions: [calculation_mismatch, missing_required_field]

```

6. Display YAML content for review

#### @implement_phase({phase_number})

Execute specific roadmap phase:

```

@implement_phase(2)

```

1. Open `auditfix.md`

2. Navigate to Phase {phase_number}

3. Announce phase title

4. Execute each step sequentially

5. Confirm completion of each step

#### @audit_invoice("{invoice_filename}")

Run full audit on specific invoice:

```

@audit_invoice("VH-87.pdf")

```

1. Search for filename in all subdirectories of `C:\all the shit\`

2. Detect company using `company_detector.py`

3. Load corresponding YAML template

4. Parse invoice with `template_parser.py`

5. Audit with `invoice_auditor.py`

6. Display formatted audit report:

```

═══════════════════════════════════════

AUDIT REPORT: VH-87.pdf

═══════════════════════════════════════

Company: VOLTA HUB ELECTRICAL TRADING

Invoice #: VH-87

Date: 2025-12-15

Total: AED 5,240.00

Field Validation: ✓ PASS

Calculation Check: ✓ PASS

Required Fields: ✓ PASS

FINAL RESULT: PASS

═══════════════════════════════════════

```

Step 4: Error Handling Protocol

When ANY error occurs:

1. **STOP IMMEDIATELY** - Do not continue execution

2. **Analyze**: Read the full error message and stack trace

3. **Context**: Identify which step/file/function caused the error

4. **Consult**: Check "Troubleshooting" sections in `auditfix.md`

5. **Propose**: Suggest a specific fix with explanation

6. **Wait**: Do not apply the fix until user approves

Example:

```

ERROR DETECTED in template_parser.py line 45:

KeyError: 'invoice_number'

Analysis: The YAML template for company "volta_hub" is missing

the 'invoice_number' field definition.

Proposed Fix: Add this section to templates/companies/volta_hub.yaml:

fields:

invoice_number:

type: regex

pattern: "Invoice #: ([A-Z0-9-]+)"

Waiting for your approval to apply this fix.

```

Step 5: Best Practices

**Always Show Your Work**:

Announce each step before execution

Display file contents after creation/modification

Summarize results after batch operations

**Never Hardcode**:

Company names → YAML `identifiers`

Field positions → YAML `fields`

Validation logic → YAML `validation`

Audit criteria → YAML `audit_rules`

**Stay Organized**:

Keep related code in appropriate modules

Follow the directory structure strictly

Use consistent naming conventions (snake_case for files/keys)

**Be Proactive**:

If a step requires a file that doesn't exist, create it

If you notice missing configuration, propose additions

If you see opportunities for automation, suggest them

Example Workflow

```

User: @create_all_company_profiles

AI: Starting bulk company profile generation...

Scanning C:\all the shit\...

Found 3 company directories:

1. VOLTA HUB ELECTRICAL TRADING CO. L.L.C

2. ABC SUPPLIES LLC

3. XYZ TRADING EST

Processing Company 1/3: VOLTA HUB ELECTRICAL TRADING CO. L.L.C

→ Generated company_key: volta_hub

→ Reference invoice: VH-87.pdf

→ Analyzing invoice structure...

→ Created templates/companies/volta_hub.yaml

✓ Complete

Processing Company 2/3: ABC SUPPLIES LLC

→ Generated company_key: abc_supplies

→ Reference invoice: ABC-001.pdf

→ Analyzing invoice structure...

→ Created templates/companies/abc_supplies.yaml

✓ Complete

Processing Company 3/3: XYZ TRADING EST

→ Generated company_key: xyz_trading

→ Reference invoice: XYZ2025-01.pdf

→ Analyzing invoice structure...

→ Created templates/companies/xyz_trading.yaml

✓ Complete

═══════════════════════════════════════

SUMMARY: Created 3 company profiles

═══════════════════════════════════════

volta_hub.yaml

abc_supplies.yaml

xyz_trading.yaml

All profiles ready for review.

```

Important Constraints

**No Manual Editing**: After initial setup, the system should run with zero manual intervention

**Phase-by-Phase**: Never skip ahead in the roadmap

**YAML First**: All business logic goes in templates, not Python

**Error Zero-Tolerance**: Stop and report on any error, no matter how small

**Reference Documentation**: Always defer to `auditfix.md` for implementation details

Success Criteria

An implementation is successful when:

1. All companies have valid YAML profiles

2. Any PDF invoice can be automatically detected, parsed, and audited

3. Audit reports are consistent and accurate

4. No hardcoded company logic exists in Python code

5. The system handles errors gracefully with clear messages

Invoice Audit System - Cursor Rules

Invoice Audit System - Cursor Rules

Overview

Core Principles

1. Template-Driven Architecture

2. File Structure

3. Processing Pipeline

Implementation Instructions

Step 1: Understand the User's Role

Step 2: Follow the Roadmap

Step 3: Handle Special Commands

Step 4: Error Handling Protocol

Step 5: Best Practices

Example Workflow

Important Constraints

Success Criteria

Reviews (0)