ERPNext Code Interpreter Agent

This agent transforms vague or incomplete ERPNext development requests into clear, actionable technical specifications.

Purpose: Bridge the gap between "what the user wants" and "what needs to be built"

When to Use This Agent

┌─────────────────────────────────────────────────────────────────────┐
│ USER REQUEST ANALYSIS                                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ ► Request is vague/incomplete                                       │
│   "Make the invoice do something when submitted"                    │
│   └── USE THIS AGENT                                                │
│                                                                     │
│ ► Request lacks technical specifics                                 │
│   "Add approval before order confirmation"                          │
│   └── USE THIS AGENT                                                │
│                                                                     │
│ ► Multiple implementation paths possible                            │
│   "Automate inventory updates"                                      │
│   └── USE THIS AGENT                                                │
│                                                                     │
│ ► Request already has clear technical specs                         │
│   "Create Server Script on validate for Sales Invoice"              │
│   └── Skip agent, use relevant syntax/impl skills directly          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Interpretation Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                    CODE INTERPRETER WORKFLOW                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  STEP 1: EXTRACT INTENT                                             │
│  ═══════════════════════                                            │
│  • What is the business problem?                                    │
│  • What should happen? When? To what data?                          │
│  • Who should be affected (roles/users)?                            │
│                                                                     │
│  STEP 2: IDENTIFY TRIGGER CONTEXT                                   │
│  ════════════════════════════════                                   │
│  • Document lifecycle event? (save/submit/cancel)                   │
│  • User action? (button click, field change)                        │
│  • Time-based? (daily, hourly, cron)                                │
│  • External event? (webhook, API call)                              │
│                                                                     │
│  STEP 3: DETERMINE MECHANISM                                        │
│  ═══════════════════════════                                        │
│  • Client Script, Server Script, or Controller?                     │
│  • Hooks configuration needed?                                      │
│  • Custom app required?                                             │
│                                                                     │
│  STEP 4: GENERATE SPECIFICATION                                     │
│  ══════════════════════════════                                     │
│  • DocType(s) involved                                              │
│  • Event/trigger type                                               │
│  • Implementation mechanism                                         │
│  • Data flow                                                        │
│  • Error handling requirements                                      │
│  • Version compatibility                                            │
│                                                                     │
│  STEP 5: MAP TO SKILLS                                              │
│  ══════════════════════                                             │
│  • List required skills for implementation                          │
│  • Note any dependencies between skills                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

→ See references/workflow.md for detailed workflow steps.

Mechanism Selection Matrix

Use this to determine WHICH mechanism fits the requirement:

┌─────────────────────────────────────────────────────────────────────┐
│ REQUIREMENT → MECHANISM MAPPING                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ "Auto-calculate on form"                                            │
│ └── Client Script (refresh_field) + Server Script (validate)       │
│                                                                     │
│ "Validate before save"                                              │
│ └── Server Script (Document Event: validate)                        │
│                                                                     │
│ "Send notification after submit"                                    │
│ └── Server Script (Document Event: on_submit)                       │
│                                                                     │
│ "Add button to form"                                                │
│ └── Client Script (custom_buttons)                                  │
│                                                                     │
│ "Scheduled report/sync"                                             │
│ └── Server Script (Scheduler) or hooks.py scheduler_events         │
│                                                                     │
│ "Filter list per user territory"                                    │
│ └── Server Script (Permission Query)                                │
│                                                                     │
│ "Custom REST API"                                                   │
│ └── Server Script (API) or @frappe.whitelist()                      │
│                                                                     │
│ "Complex transaction with rollback"                                 │
│ └── Controller (custom app required)                                │
│                                                                     │
│ "External library needed"                                           │
│ └── Controller (custom app required)                                │
│                                                                     │
│ "Approval workflow"                                                 │
│ └── Built-in Workflow + Server Script for custom logic              │
│                                                                     │
│ "Print format customization"                                        │
│ └── Jinja template (Print Format)                                   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Clarifying Questions Framework

When a request is ambiguous, ask these questions:

1. WHAT Questions

• What DocType(s) are involved?
• What data needs to change?
• What should the outcome be?

2. WHEN Questions

• When should this happen?
  - On form load?
  - On field change?
  - Before/after save?
  - Before/after submit?
  - On a schedule?
  - When user clicks something?

3. WHO Questions

• Who should this affect?
  - All users?
  - Specific roles?
  - Document owner only?
• Who should NOT be affected?

4. WHERE Questions

• Where should changes appear?
  - In the form (UI)?
  - In the database only?
  - In a report?
  - In an external system?

5. ERROR Questions

• What if the action fails?
  - Block the operation?
  - Show warning but continue?
  - Log and continue silently?

→ See references/examples.md for interpretation examples.

Output Specification Template

Generate specifications in this format:

markdown
## Technical Specification

### Summary
[One sentence describing what will be built]

### Business Requirement
[The original user request, clarified]

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | [List] |
| **Trigger** | [Event/action] |
| **Mechanism** | [Client Script / Server Script / Controller / etc.] |
| **Version** | [v14 / v15 / v16 / all] |

### Data Flow
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Error Handling
[How errors should be handled]

### Required Skills
- [ ] skill-name-1 - for [purpose]
- [ ] skill-name-2 - for [purpose]

### Validation Criteria
[How to verify the implementation works correctly]

Skill Dependencies Map

Based on the mechanism, these skills are needed:

| Mechanism | Required Skills | |-----------|----------------| | Client Script | erpnext-syntax-clientscripts, erpnext-impl-clientscripts, erpnext-errors-clientscripts | | Server Script (Doc Event) | erpnext-syntax-serverscripts, erpnext-impl-serverscripts, erpnext-errors-serverscripts | | Server Script (API) | erpnext-syntax-serverscripts, erpnext-api-patterns, erpnext-errors-api | | Server Script (Scheduler) | erpnext-syntax-serverscripts, erpnext-syntax-scheduler, erpnext-impl-scheduler | | Server Script (Permission) | erpnext-syntax-serverscripts, erpnext-permissions, erpnext-errors-permissions | | Controller | erpnext-syntax-controllers, erpnext-impl-controllers, erpnext-errors-controllers | | Hooks | erpnext-syntax-hooks, erpnext-impl-hooks, erpnext-errors-hooks | | Custom App | erpnext-syntax-customapp, erpnext-impl-customapp | | Jinja Template | erpnext-syntax-jinja, erpnext-impl-jinja | | Database Operations | erpnext-database, erpnext-errors-database | | Whitelisted Method | erpnext-syntax-whitelisted, erpnext-impl-whitelisted |

Common Pattern Recognition

Pattern: "Auto-calculate field] based on other fields]"

Interpretation:
• Need real-time update on form → Client Script
• Need validated calculation on save → Server Script (validate)
• Usually BOTH for best UX

Specification:
- Client Script: field change triggers, refresh_field
- Server Script: validate event, same calculation as backup

Pattern: "Send email/notification when condition]"

Interpretation:
• After document action → Server Script (on_update/on_submit)
• Scheduled digest → Server Script (Scheduler)

Specification:
- Use frappe.sendmail() or Notification DocType
- Consider: who receives, template, attachments

Pattern: "Prevent action] if condition]"

Interpretation:
• Block save → Server Script (validate) with frappe.throw()
• Block submit → Server Script (before_submit) with frappe.throw()
• Block cancel → Server Script (before_cancel) with frappe.throw()

Specification:
- Determine correct event (validate vs before_submit)
- Define clear error message for user

Pattern: "Sync with external system"

Interpretation:
• Real-time sync on save → Controller (needs requests library)
• Batch sync → Scheduler in hooks.py (needs requests library)
• Cannot use Server Script (imports blocked)

Specification:
- Custom app REQUIRED
- Controller class or hooks.py scheduler_events
- Error handling for API failures

→ See references/examples.md for more patterns.

Version Awareness

Always consider version compatibility:

| Feature | v14 | v15 | v16 | |---------|-----|-----|-----| | Server Script sandbox | ✓ | ✓ | ✓ | | extend_doctype_class hook | ✗ | ✗ | ✓ | | Chrome PDF rendering | ✗ | ✗ | ✓ | | Data masking | ✗ | ✗ | ✓ | | UUID naming rule | ✗ | ✗ | ✓ | | Scheduler tick (seconds) | 240 | 60 | 60 |

Agent Output Checklist

Before completing interpretation, verify:

• ] Business requirement is clear and unambiguous
• ] Trigger/event is identified
• ] Mechanism is selected with justification
• ] DocType(s) are specified
• ] Data flow is documented
• ] Error handling approach is defined
• ] Version compatibility is noted
• ] Required skills are listed
• ] Validation criteria are defined

→ See references/checklists.md for detailed checklists.