Self-Improving Finance Skill#

Log finance-specific learnings, operational issues, and feature requests to markdown files for continuous improvement. Captures reconciliation errors, forecast variances, control weaknesses, regulatory gaps, valuation errors, and cash flow anomalies. Important learnings get promoted to close checklists, reconciliation procedures, control matrices, tax calendars, forecast models, or audit response templates.

First-Use Initialisation#

Before logging anything, ensure the .learnings/ directory and files exist in the project or workspace root. If any are missing, create them:

bash

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Finance Learnings\n\nReconciliation errors, control weaknesses, forecast variances, regulatory gaps, valuation errors, and cash flow anomalies captured during finance operations.\n\n**Categories**: reconciliation_error | forecast_variance | control_weakness | regulatory_gap | valuation_error | cash_flow_anomaly\n**Areas**: accounting | treasury | tax | audit | budgeting | reporting | accounts_payable | accounts_receivable\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/FINANCE_ISSUES.md ] || printf "# Finance Issues Log\n\nReconciliation breaks, control failures, forecast misses, regulatory findings, and cash flow anomalies.\n\n---\n" > .learnings/FINANCE_ISSUES.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nFinance tools, automation capabilities, and process improvements requested during finance operations.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

Never overwrite existing files. This is a no-op if .learnings/ is already initialised.

IMPORTANT — Data Sensitivity: NEVER log actual account numbers, bank routing numbers, specific financial figures for real entities, audit findings with client names, taxpayer identification numbers, or any personally identifiable financial information. Always abstract and anonymize. Use placeholders like "Entity A", "$X.XM", "Account XXXX-1234", or percentage-based descriptions. Financial data is highly regulated under SOX, GDPR, PCI-DSS, and other frameworks. Treat all logged content as if it could be read by an external auditor.

If you want automatic reminders, use the opt-in hook workflow described in Hook Integration.

Quick Reference#

SituationActionReconciliation break identifiedLog to .learnings/FINANCE_ISSUES.md with reconciliation detailsBudget vs. actual variance >10%Log to .learnings/FINANCE_ISSUES.md with variance analysisSOX control test failsLog to .learnings/FINANCE_ISSUES.md with control failure detailsLate close item discoveredLog to .learnings/FINANCE_ISSUES.md with deadline impactIntercompany imbalance foundLog to .learnings/FINANCE_ISSUES.md with entity mismatchUnusual journal entry flagged by auditLog to .learnings/FINANCE_ISSUES.md with JE anomalyAR aging past 90 daysLog to .learnings/FINANCE_ISSUES.md with aging bucket analysisControl weakness identifiedLog to .learnings/LEARNINGS.md with category control_weaknessRegulatory gap discoveredLog to .learnings/LEARNINGS.md with category regulatory_gapValuation model errorLog to .learnings/LEARNINGS.md with category valuation_errorCash flow anomaly detectedLog to .learnings/LEARNINGS.md with category cash_flow_anomalyForecast methodology improvementLog to .learnings/LEARNINGS.md with category forecast_varianceRecurring reconciliation patternLink with **See Also**, consider priority bumpBroadly applicable procedurePromote to close checklist, control matrix, or reconciliation procedure

OpenClaw Setup (Recommended)#

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

Installation#

Via ClawdHub (recommended):

bash

clawdhub install self-improving-finance

Manual:

bash

git clone https://github.com/jose-compu/self-improving-finance.git ~/.openclaw/skills/self-improving-finance

Workspace Structure#

OpenClaw injects these files into every session:

text

~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── FINANCE_ISSUES.md
    └── FEATURE_REQUESTS.md

Create Learning Files#

bash

mkdir -p ~/.openclaw/workspace/.learnings

Then create the log files (or copy from assets/):

• LEARNINGS.md — reconciliation errors, control weaknesses, forecast variances, regulatory gaps, valuation errors, cash flow anomalies
• FINANCE_ISSUES.md — reconciliation breaks, control failures, regulatory findings, close delays
• FEATURE_REQUESTS.md — finance tools, automation, reporting capabilities

Promotion Targets#

When finance learnings prove broadly applicable, promote them:

Learning TypePromote ToExampleClose proceduresClose checklists"Verify intercompany eliminations before consolidation"Reconciliation patternsReconciliation procedures"Three-way match for AP: PO, receipt, invoice"Control gapsControl matrices"Journal entries >$X require dual approval"Tax complianceTax calendars"Embedded lease review before ASC 842 filing"Forecast improvementsForecast models"Weight pipeline deals by stage probability"Audit findingsAudit response templates"Standard response for revenue recognition inquiries"Workflow patternsAGENTS.md"Run trial balance before close meeting"

Optional: Enable Hook#

Opt-in and project-scoped. Enabling a hook persists across future sessions; skip this unless you need reminders:

bash

cp -r hooks/openclaw ~/.openclaw/hooks/self-improving-finance
openclaw hooks enable self-improving-finance

See references/openclaw-integration.md for complete details.

---

Generic Setup (Other Agents)#

For Claude Code, Codex, Copilot, or other agents, create .learnings/ in the project or workspace root:

bash

mkdir -p .learnings

Create the files inline using the headers shown above.

Add reference to agent files#

Add to AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md:

Self-Improving Finance Workflow

When finance issues or patterns are discovered:

1. Log to .learnings/FINANCE_ISSUES.md, LEARNINGS.md, or FEATURE_REQUESTS.md
2. Review and promote broadly applicable learnings to:
   • Close checklists — month-end and quarter-end close procedures
   • Reconciliation procedures — step-by-step account reconciliation guides
   • Control matrices — SOX controls, approval workflows, segregation of duties
   • Tax calendars — filing deadlines, compliance milestones
   • Forecast models — revenue and expense projection methodologies
   • Audit response templates — standard responses for common audit inquiries

Logging Format#

Learning Entry [LRN-YYYYMMDD-XXX]#

Append to .learnings/LEARNINGS.md:

markdown

## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: accounting | treasury | tax | audit | budgeting | reporting | accounts_payable | accounts_receivable

### Summary
One-line description of the finance insight

### Details
Full context: what reconciliation error, control gap, or valuation issue was found,
why it matters for financial accuracy, and what the correct procedure or treatment is.
Include anonymized figures and account references.

### Correct Treatment

**Before (incorrect):**
Description of the incorrect accounting treatment, reconciliation approach,
or control procedure. Use anonymized examples only.

**After (correct):**
Description of the correct treatment, procedure, or control.

### Suggested Action
Specific process change, control enhancement, or procedure update to adopt.
Reference applicable standards (ASC, IFRS, SOX section) where relevant.

### Metadata
- Source: reconciliation | close_review | audit_finding | variance_analysis | control_test | regulatory_update
- Framework: US_GAAP | IFRS | SOX | local_GAAP
- Related Accounts: anonymized account references
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: reconciliation.fx_conversion | control.approval_bypass (optional)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---

Categories for learnings:

CategoryUse Whenreconciliation_errorAccount balance discrepancy, bank rec break, intercompany mismatchforecast_varianceBudget vs. actual deviation, revenue miss, expense overruncontrol_weaknessMissing approval, segregation of duties gap, access control issueregulatory_gapNon-compliance with accounting standard, missed regulatory requirementvaluation_errorIncorrect fair value, wrong depreciation method, impairment oversightcash_flow_anomalyUnexpected cash movement, timing difference, liquidity event

Finance Issue Entry [FIN-YYYYMMDD-XXX]#

Append to .learnings/FINANCE_ISSUES.md:

markdown

## [FIN-YYYYMMDD-XXX] issue_type

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: accounting | treasury | tax | audit | budgeting | reporting | accounts_payable | accounts_receivable

### Summary
Brief description of the finance issue (anonymized)

### Issue Details
What was found during reconciliation, close, audit, or analysis.
Include anonymized amounts, account references, and entity names.
NEVER include real account numbers, bank details, or client names.

### Root Cause
What process gap, system error, or procedural failure caused this issue.

### Impact
- Financial statement impact (material / immaterial, estimated range)
- Regulatory exposure (SOX deficiency classification if applicable)
- Operational impact (close delay, restatement risk, cash flow effect)

### Remediation
Steps taken or recommended to resolve the issue and prevent recurrence.
Reference control framework requirements where applicable.

### Context
- Trigger: reconciliation | close_review | audit | variance_analysis | control_test | aging_review
- Period: fiscal quarter or month affected
- Entity: anonymized entity reference
- System: ERP, GL, or sub-ledger involved

### Metadata
- Materiality: material | immaterial | pending_assessment
- Related Accounts: anonymized references
- See Also: FIN-20250110-001 (if recurring)

---

Feature Request Entry [FEAT-YYYYMMDD-XXX]#

Append to .learnings/FEATURE_REQUESTS.md:

markdown

## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: accounting | treasury | tax | audit | budgeting | reporting | accounts_payable | accounts_receivable

### Requested Capability
What finance tool, automation, or process improvement is needed

### User Context
Why it's needed, what workflow it improves, what risk it mitigates

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built: ERP configuration, report template, reconciliation script,
control automation, or process redesign

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_tool_or_process

---

ID Generation#

Format: TYPE-YYYYMMDD-XXX

• TYPE: LRN (learning), FIN (finance issue), FEAT (feature request)
• YYYYMMDD: Current date
• XXX: Sequential number or random 3 chars (e.g., 001, A7B)

Examples: LRN-20250415-001, FIN-20250415-A3F, FEAT-20250415-002

Resolving Entries#

When an issue is resolved, update the entry:

1. Change **Status**: pending → **Status**: resolved
2. Add resolution block after Metadata:

markdown

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Reference**: adjusting JE #1234 or control remediation ticket
- **Notes**: Updated reconciliation procedure / added control step / revised forecast model

Other status values:

• in_progress — Actively being remediated or investigated
• wont_fix — Determined immaterial or accepted risk (add reason in Resolution notes)
• promoted — Elevated to close checklist, control matrix, or reconciliation procedure
• promoted_to_skill — Extracted as a reusable skill

Detection Triggers#

Automatically log when you encounter:

Reconciliation Breaks (→ finance issue with reconciliation trigger):

• Account balance discrepancy of any amount (reconciliation difference >$0)
• Bank reconciliation unreconciled items
• Intercompany balance mismatch between entities
• Sub-ledger to general ledger variance

Budget & Forecast Variances (→ finance issue with variance_analysis trigger):

• Budget vs. actual variance exceeding 10% on any line item
• Revenue forecast miss by more than one standard deviation
• Capital expenditure overrun vs. approved budget

Control Failures (→ finance issue with control_test trigger):

• SOX control test failure (key control or compensating control)
• Journal entry exceeding materiality threshold without dual approval
• Segregation of duties violation detected
• Access control exception (unauthorized GL posting)

Close Process Issues (→ finance issue with close_review trigger):

• Close task past its deadline
• Pending adjusting entries at close cutoff
• Unresolved reconciling items carried forward

Audit Flags (→ finance issue with audit trigger):

• Unusual journal entry flagged (round amounts, off-hours posting, above threshold)
• Revenue recognition timing question
• Related-party transaction without proper disclosure

Receivables & Payables (→ finance issue with aging_review trigger):

• AR aging spike past 90 days (concentration or volume)
• Duplicate payment detected in AP
• Vendor invoice without purchase order match

Regulatory & Standards (→ learning with regulatory_gap category):

• New accounting standard not yet implemented (ASC, IFRS updates)
• Tax law change affecting current period
• Transfer pricing documentation gap

Priority Guidelines#

PriorityWhen to UseFinance ExamplescriticalMaterial misstatement risk, regulatory penalty exposureRestatement required, SEC comment letter, material weakness in ICFRhighSOX control failure, reconciliation break, cash flow crisisKey control deficiency, unreconciled bank balance >materiality, covenant breach riskmediumForecast variance, process improvement, non-critical control gapQ3 revenue 15% below forecast, manual workaround in close process, compensating control relied uponlowDocumentation update, minor procedure enhancementReconciliation template needs update, naming convention for GL accounts, archive policy for supporting schedules

Area Tags#

Use to filter learnings by finance domain:

AreaScopeaccountingGeneral ledger, journal entries, chart of accounts, period close, consolidationtreasuryCash management, bank relationships, debt/investment, FX exposure, liquiditytaxIncome tax provision, sales/use tax, transfer pricing, tax compliance filingsauditInternal audit, external audit support, SOX testing, control documentationbudgetingAnnual budget, rolling forecasts, variance analysis, capital planningreportingFinancial statements, management reporting, regulatory filings, board packagesaccounts_payableVendor invoices, payment processing, three-way match, 1099 reportingaccounts_receivableCustomer invoicing, collections, credit memos, aging analysis, bad debt

Promoting to Permanent Finance Procedures#

When a learning is broadly applicable (not a one-off adjustment), promote it to permanent finance standards.

When to Promote#

• Reconciliation issue recurs across multiple periods or entities
• Control gap is found in 2+ process areas
• Regulatory interpretation applies to all entities under the same framework
• Close procedure improvement saves measurable time

Promotion Targets#

TargetWhat Belongs ThereClose checklistsPeriod-end tasks, cutoff procedures, sign-off requirementsReconciliation proceduresStep-by-step account rec guides, tolerance thresholds, escalation pathsControl matricesSOX key controls, compensating controls, control owners, test proceduresTax calendarsFiling deadlines, estimated payment dates, compliance milestonesForecast modelsRevenue drivers, expense assumptions, sensitivity parametersAudit response templatesStandard responses for common audit inquiries and requestsAGENTS.mdAutomated finance workflows, pre-close checks

How to Promote#

1. Distill the learning into a concise procedure, control step, or checklist item

2. Add to appropriate target (close checklist entry, control matrix row, reconciliation step)

3. Show a reviewed diff and apply only after explicit user approval

4. Update original entry:

   • Change **Status**: pending → **Status**: promoted
   • Add **Promoted**: close checklist (or control matrix, reconciliation procedure, tax calendar, forecast model, audit response template)

Promotion Examples#

Learning (verbose):

Found FX conversion for P&L items using spot rate at transaction date instead of average rate for the period. This affected three subsidiaries and caused a $X.XM translation variance that required a top-side adjustment at consolidation.

As close checklist item (concise):

☐ Verify FX rates applied to P&L items use weighted-average rate for the period, not spot rate. Cross-check against rate table published by treasury.

Learning (verbose):

Journal entries under $10K were bypassing the approval workflow due to a threshold misconfiguration in the ERP. This was discovered during SOX testing when 47 entries in Q2 had no approver stamp.

As control matrix entry (actionable):

Control IDDescriptionOwnerFrequencyEvidenceJE-001All journal entries require dual approval regardless of amountControllerPer occurrenceApprover signature in ERP workflow

Recurring Pattern Detection#

If logging something similar to an existing entry:

1. Search first: grep -r "keyword" .learnings/

2. Link entries: Add **See Also**: FIN-20250110-001 in Metadata

3. Bump priority if issue keeps recurring

4. Consider systemic fix: Recurring finance issues often indicate:

   • Missing close checklist step (→ add to close checklist)
   • Incomplete control design (→ update control matrix)
   • System configuration gap (→ ERP configuration change request)
   • Training gap (→ add to onboarding documentation)

Periodic Review#

Review .learnings/ at natural breakpoints in the finance calendar:

When to Review#

• Before each month-end close or after completing a close cycle
• When the same reconciliation issue recurs
• During quarterly SOX testing or before annual audit fieldwork

Quick Status Check#

bash

# Count pending finance issues
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority finance issues
grep -B5 "Priority\*\*: high" .learnings/FINANCE_ISSUES.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: treasury" .learnings/*.md

# Find all control weaknesses
grep -B2 "control_weakness" .learnings/LEARNINGS.md | grep "^## \["

# Find all reconciliation errors
grep -B2 "reconciliation_error" .learnings/LEARNINGS.md | grep "^## \["

Review Actions#

• Resolve remediated finance issues
• Promote recurring patterns to close checklists or control matrices
• Link related entries across files
• Extract reusable procedures as skills

Simplify & Harden Feed#

Ingest recurring finance patterns from simplify-and-harden into close checklists or control matrices.

1. For each candidate, use pattern_key as the dedupe key.
2. Search .learnings/LEARNINGS.md for existing entry: grep -n "Pattern-Key: <key>" .learnings/LEARNINGS.md
3. If found: increment Recurrence-Count, update Last-Seen, add See Also links.
4. If not found: create new LRN-... entry with Source: simplify-and-harden.

Promotion threshold: Recurrence-Count >= 3, seen in 2+ periods or entities, within 90-day window. Targets: close checklists, reconciliation procedures, control matrices, AGENTS.md.

Hook Integration#

Enable automatic reminders through agent hooks. This is opt-in.

Hooks persist across sessions once installed. Keep them project-scoped. Do not install user-level or global hooks. Never use an empty matcher. PostToolUse inspects command output in-process; do not log raw output, secrets, or transcripts.

Quick Setup (Claude Code / Codex)#

Create .claude/settings.json in your project:

json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "reconcil|variance|close|audit|SOX|budget|forecast|materiality",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-finance/scripts/activator.sh"
      }]
    }]
  }
}

This injects a finance-focused learning evaluation reminder after matching prompts (~50-100 tokens overhead).

Advanced Setup (With Error Detection)#

json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "reconcil|variance|close|audit|SOX|budget|forecast|materiality",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-finance/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-finance/scripts/error-detector.sh"
      }]
    }]
  }
}

Enable PostToolUse only if you want the hook to inspect command output for reconciliation issues, variances, and control failures.

Available Hook Scripts#

ScriptHook TypePurposescripts/activator.shUserPromptSubmitReminds to evaluate finance learnings after tasksscripts/error-detector.shPostToolUse (Bash)Triggers on reconciliation breaks, variances, control test output

See references/hooks-setup.md for detailed configuration and troubleshooting.

Automatic Skill Extraction#

Extracted skills are untrusted until a human reviews the generated SKILL.md. Do not keep or publish an extracted skill without explicit user approval.

When a finance learning is valuable enough to become a reusable skill, extract it.

Skill Extraction Criteria#

CriterionDescriptionRecurringSame reconciliation or control issue in 2+ periods or entitiesVerifiedStatus is resolved with confirmed remediationNon-obviousRequired investigation beyond standard proceduresBroadly applicableNot entity-specific; useful across the finance organizationUser-flaggedUser says "save this as a skill" or similar

Extraction Workflow#

1. Identify candidate: Learning meets extraction criteria

2. Run helper (or create manually): bash

   ./skills/self-improving-finance/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improving-finance/scripts/extract-skill.sh skill-name
   
   

3. Customize SKILL.md: Fill in template with finance-specific content

4. Update learning: Set status to promoted_to_skill, add Skill-Path

5. Verify: Read skill in fresh session to ensure it's self-contained

Extraction Detection Triggers#

In conversation: "This reconciliation keeps breaking", "Save this close procedure as a skill", "We hit this same control gap last quarter", "Every entity has this intercompany issue".

In entries: Multiple See Also links, high priority + resolved, control_weakness or reconciliation_error with broad applicability, same Pattern-Key across entities.

Multi-Agent Support#

AgentActivationDetectionClaude CodeHooks (UserPromptSubmit, PostToolUse)Automatic via error-detector.shCodex CLIHooks (same pattern)Automatic via hook scriptsGitHub CopilotManual ( .github/copilot-instructions.md)Manual reviewOpenClawWorkspace injection + inter-agent messagingVia session tools

Finance Best Practices#

1. Reconcile daily — do not wait until close to identify breaks
2. Four-eyes principle — every journal entry, payment, and adjustment requires a second reviewer
3. Segregation of duties — the person who initiates a transaction must not be the person who approves it
4. Maintain audit trail — every adjustment must have supporting documentation and a clear rationale
5. Close on schedule — late close items compound; escalate at the first sign of delay
6. Track materiality thresholds — know the quantitative thresholds for your entity and apply them consistently
7. Anonymize all logged data — never record real account numbers, bank details, or client-identifying information
8. Log immediately — context around reconciliation breaks and control failures fades fast
9. Reference applicable standards — cite ASC, IFRS, SOX section, or internal policy numbers
10. Promote after review when recurrence appears — if the same issue appears in two periods, it deserves a checklist item or control update

Gitignore Options#

Add .learnings/ to .gitignore for local-only; omit for org-wide sharing; or ignore *.md but keep .gitkeep for a hybrid approach.

Stackability Contract (Standalone + Multi-Skill)#

This skill is standalone-compatible and stackable with other self-improving skills.

Namespaced Logging (recommended for 2+ skills)#

• Namespace for this skill: .learnings/finance/
• Keep current standalone behavior if you prefer flat files.
• Optional shared index for all skills: .learnings/INDEX.md

Required Metadata#

Every new entry must include:

markdown

**Skill**: finance

Hook Arbitration (when 2+ skills are enabled)#

• Use one dispatcher hook as the single entrypoint.
• Dispatcher responsibilities: route by matcher, dedupe repeated events, and rate-limit reminders.
• Suggested defaults: dedupe key = event + matcher + file + 5m_window; max 1 reminder per skill every 5 minutes.

Narrow Matcher Scope (finance)#

Only trigger this skill automatically for finance signals such as:

• reconciliation|journal entry|close process|variance|materiality
• sox control|audit evidence|cash flow|forecast miss
• explicit finance intent in user prompt

Cross-Skill Precedence#

When guidance conflicts, apply:

1. security
2. engineering
3. coding
4. ai
5. user-explicit domain skill
6. meta as tie-breaker

Ownership Rules#

• This skill writes only to .learnings/finance/ in stackable mode.
• It may read other skill folders for cross-linking, but should not rewrite their entries.
• Standalone mode writes to this project's .learnings/*.md log files only.
• Stackable mode writes only to the namespaced folder above and must not rewrite other skills' log entries.
• Promotion into AGENTS.md, SOUL.md, TOOLS.md, MEMORY.md, rules, hooks, or generated skills is not a logging write. Show a reviewed diff and apply only after explicit user approval.