Self-Improving Supply Chain

Self-Improving Supply Chain Skill

Log supply chain learnings, disruption patterns, and feature requests to markdown files for continuous improvement. Captures forecast errors, supplier risks, logistics delays, inventory mismatches, quality deviations, and demand signal shifts. Important learnings get promoted to supplier scorecards, safety stock policies, routing playbooks, demand planning models, or quality acceptance criteria.

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:

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Supply Chain Learnings\n\nForecast errors, supplier risks, logistics delays, inventory mismatches, quality deviations, and demand signal shifts captured during operations.\n\nCategories: forecast_error | supplier_risk | logistics_delay | inventory_mismatch | quality_deviation | demand_signal_shift\nAreas: procurement | inventory | logistics | manufacturing | quality | demand_planning | warehousing\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/SUPPLY_CHAIN_ISSUES.md ] || printf "# Supply Chain Issues Log\n\nStockouts, delivery delays, supplier failures, quality rejections, and capacity breaches.\n\n---\n" > .learnings/SUPPLY_CHAIN_ISSUES.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nSupply chain tools, automation capabilities, and operational improvements.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

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

Do not log proprietary supplier pricing, negotiated contract terms, or customer-identifiable order data. Prefer aggregated metrics and redacted summaries over raw PO numbers or customer names. This skill is documentation-only: it does not execute purchases, place orders, trigger procurement transactions, or call external payment systems.

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

Quick Reference

| Situation | Action | |-----------|--------| | Stockout event detected | Log to .learnings/SUPPLY_CHAIN_ISSUES.md with category inventory_mismatch | | Delivery late or SLA missed | Log to .learnings/SUPPLY_CHAIN_ISSUES.md with category logistics_delay | | Supplier lead time increased | Log to .learnings/LEARNINGS.md with category supplier_risk | | Quality rejection or defect spike | Log to .learnings/SUPPLY_CHAIN_ISSUES.md with category quality_deviation | | Demand forecast off by >15% | Log to .learnings/LEARNINGS.md with category forecast_error | | Warehouse at or above 90% capacity | Log to .learnings/SUPPLY_CHAIN_ISSUES.md with category inventory_mismatch | | Demand spike from external signal | Log to .learnings/LEARNINGS.md with category demand_signal_shift | | Recurring supply chain pattern | Link with See Also, consider priority bump | | Broadly applicable pattern | Promote to scorecard, policy, playbook, or model | | Reusable operational process | Promote to skill extraction |

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):

clawdhub install self-improving-supply-chain

Manual:

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

Workspace Structure

OpenClaw injects these files into every session:

~/.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
    ├── SUPPLY_CHAIN_ISSUES.md
    └── FEATURE_REQUESTS.md

Create Learning Files

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

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

Promotion Targets

When supply chain learnings prove broadly applicable, promote them:

| Learning Type | Promote To | Example | |---------------|------------|---------| | Supplier performance patterns | Supplier scorecards | "Require dual-source for components >$50K annual spend" | | Inventory buffer patterns | Safety stock policies | "Ocean-freight SKUs carry 3 weeks safety stock" | | Routing optimizations | Routing playbooks | "Divert to Nansha when Yantian queue >5 days" | | Forecast accuracy patterns | Demand planning models | "Apply seasonal index for gift-category Q4 SKUs" | | Quality failure patterns | Quality acceptance criteria | "100% inspection on first shipment from new suppliers" | | Workflow patterns | AGENTS.md | "Run inventory reconciliation before reorder point calc" |

Optional: Enable Hook

For automatic reminders at session start:

cp -r hooks/openclaw ~/.openclaw/hooks/self-improving-supply-chain
openclaw hooks enable self-improving-supply-chain

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:

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 Supply Chain Workflow

When supply chain disruptions or patterns are discovered: 1. Log to .learnings/SUPPLY_CHAIN_ISSUES.md, LEARNINGS.md, or FEATURE_REQUESTS.md 2. Review and promote broadly applicable learnings to: - Supplier scorecards — performance thresholds, risk tiers, qualification requirements - Safety stock policies — buffer calculations, service level targets, review cadence - Routing playbooks — contingency routes, mode-shift triggers, carrier selection - Demand planning models — seasonal indices, channel mix adjustments, event-driven overlays

Logging Format

Learning Entry [LRN-YYYYMMDD-XXX]

Append to .learnings/LEARNINGS.md:

## [LRN-YYYYMMDD-XXX] category
Logged: ISO-8601 timestamp
Priority: low | medium | high | critical
Status: pending
Area: procurement | inventory | logistics | manufacturing | quality | demand_planning | warehousing
Summary
One-line description of the supply chain insight
Details
Full context: what operational condition was observed, why it matters,
what the root cause is, and what the downstream impact was.
Include quantified metrics where possible (units, cost, days, fill rate).
Impact
Units affected: X
Cost impact: $Y
Duration: Z days
Service level impact: from A% to B%
Suggested Action
Specific policy change, process improvement, or operational adjustment to adopt
Metadata
Source: demand_forecast_review | supplier_communication | warehouse_audit | quality_inspection | order_management | logistics_tracking
SKU/Component: identifier (if applicable)
Supplier: name and code (if applicable)
Related Files: path/to/file.ext
Tags: tag1, tag2
See Also: LRN-20250110-001 (if related to existing entry)
Pattern-Key: forecast_error.seasonal_miss | supplier_risk.single_source (optional)
Recurrence-Count: 1 (optional)
First-Seen: 2025-01-15 (optional)
Last-Seen: 2025-01-15 (optional)

Categories for learnings:

| Category | Use When | |----------|----------| | forecast_error | Demand forecast deviates significantly from actuals (MAPE >15%) | | supplier_risk | Supplier lead time increase, financial distress, capacity constraint, single-source exposure | | logistics_delay | Shipment delay, port congestion, carrier failure, customs hold, routing inefficiency | | inventory_mismatch | WMS vs physical count variance, stockout, overstock, expired inventory, capacity breach | | quality_deviation | Defect rate spike, inspection failure, non-conformance, recall, specification drift | | demand_signal_shift | Unexpected demand change from viral event, channel shift, competitor action, regulation |

Supply Chain Issue Entry [SCM-YYYYMMDD-XXX]

Append to .learnings/SUPPLY_CHAIN_ISSUES.md:

## [SCM-YYYYMMDD-XXX] category
Logged: ISO-8601 timestamp
Priority: high
Status: pending
Area: procurement | inventory | logistics | manufacturing | quality | demand_planning | warehousing
Summary
Brief description of the supply chain disruption or issue
Details
What happened, when, where in the supply chain, and what triggered it.
Impact
Units affected: X
Cost impact: $Y (direct + indirect)
Duration: Z days
Customer impact: fill rate drop, delayed orders, SLA breach
Mitigation Steps
1. Immediate containment action
2. Short-term workaround
3. Root cause investigation
4. Long-term corrective action
Root Cause
What in the supply chain caused this issue. Include contributing factors.
Context
Trigger: stockout_event | delivery_sla_miss | supplier_lead_time_increase | quality_rejection_spike | forecast_variance | capacity_breach
Carrier/Supplier: name and code
Route/Lane: origin → destination
SKU/Component: identifiers affected
Metadata
Reproducible: yes | no | seasonal | event_driven
Related Files: path/to/file.ext
See Also: SCM-20250110-001 (if recurring)

Feature Request Entry [FEAT-YYYYMMDD-XXX]

Append to .learnings/FEATURE_REQUESTS.md:

## [FEAT-YYYYMMDD-XXX] capability_name
Logged: ISO-8601 timestamp
Priority: medium
Status: pending
Area: procurement | inventory | logistics | manufacturing | quality | demand_planning | warehousing
Requested Capability
What supply chain tool, automation, or capability is needed
User Context
Why it's needed, what workflow it improves, what operational problem it solves
Complexity Estimate
simple | medium | complex
Suggested Implementation
How this could be built: dashboard, integration, alert system, optimization model, workflow automation
Metadata
Frequency: first_time | recurring
Related Features: existing_tool_or_system

ID Generation

Format: TYPE-YYYYMMDD-XXX

Examples: LRN-20250415-001, SCM-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:

### Resolution
Resolved: 2025-01-16T09:00:00Z
Corrective Action: policy change / supplier qualification / routing update / safety stock adjustment
Notes: Description of what was done and verification of effectiveness

Other status values:

Detection Triggers

Automatically log when you encounter:

Inventory Below Safety Stock (→ supply chain issue with inventory_mismatch):

Delivery Tracking Shows Delay (→ supply chain issue with logistics_delay):

Supplier Communication Indicating Lead Time Change (→ learning with supplier_risk):

Quality Inspection Failure Rate >2% (→ supply chain issue with quality_deviation):

Demand Forecast MAPE >15% (→ learning with forecast_error):

Warehouse Utilization >90% (→ supply chain issue with inventory_mismatch):

Priority Guidelines

| Priority | When to Use | Supply Chain Examples | |----------|-------------|----------------------| | critical | Production line stopped, customer order unfulfillable, safety/recall issue | Factory shut down waiting for parts, complete stockout on top-10 SKU, product recall initiated | | high | Stockout imminent, supplier failure likely, major SLA breach | Safety stock below 3 days, sole-source supplier in financial distress, 50+ orders delayed | | medium | Forecast accuracy degradation, routing inefficiency, quality trend | MAPE trending up over 3 months, suboptimal carrier selection, rejection rate at 1.5% | | low | Process documentation, minor optimization, data cleanup | SOP update needed, rounding error in forecast, warehouse label format change |

Area Tags

Use to filter learnings by supply chain domain:

| Area | Scope | |------|-------| | procurement | Supplier selection, PO management, contract negotiation, spend analysis, qualification | | inventory | Safety stock, reorder points, cycle counting, ABC classification, obsolescence | | logistics | Freight, routing, carrier management, customs, last-mile, mode selection | | manufacturing | Production planning, BOM management, capacity, yield, changeover | | quality | Inspection, SCAR, non-conformance, acceptance criteria, certification | | demand_planning | Forecasting, seasonal decomposition, promotional planning, new product introduction | | warehousing | Storage, picking, packing, receiving, put-away, layout, capacity |

Promoting to Permanent Operational Standards

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

When to Promote

Promotion Targets

| Target | What Belongs There | |--------|-------------------| | Supplier scorecards | Performance thresholds, risk tier definitions, qualification requirements | | Safety stock policies | Buffer calculations by sourcing mode, service level targets, review cadence | | Routing playbooks | Contingency routes, mode-shift triggers, carrier escalation matrix | | Demand planning models | Seasonal indices, event overlays, channel mix assumptions | | Quality acceptance criteria | Inspection sampling plans, reject thresholds, first-article requirements | | AGENTS.md | Automated operational workflows, pre-reorder checks |

How to Promote

1. Distill the learning into a concise rule or policy statement 2. Add to appropriate target (scorecard, policy, playbook, model) 3. Update original entry: - Change Status: pending → Status: promoted - Add Promoted: safety stock policy (or supplier scorecard, routing playbook, demand model, quality criteria)

Promotion Examples

Learning (verbose): > Ocean-freight SKUs experience 10-21 day lead time variability. Existing 2-week > safety stock insufficient — caused 4 stockouts in 6 months.

As safety stock policy (concise):

## Ocean-Freight Safety Stock
Buffer: 3 weeks of average weekly demand
Review: quarterly against actual lead time data
Trigger: adjust if lead time std dev changes >20%

Learning (verbose): > Port congestion at Yantian added 14 days to 12 containers. Diverting to Nansha > saved 7 days on 4 containers. West Coast routing avoided congestion entirely.

As routing playbook (actionable):

## Yantian Congestion Response
1. Monitor Yantian vessel queue daily via CargoSmart
2. If berthing wait >5 days: divert new bookings to Nansha
3. If congestion >10 days: activate West Coast routing via Long Beach
4. Air-freight top 8 critical SKUs if customer SLA at risk
5. Notify customer service for affected order ETAs

Recurring Pattern Detection

If logging something similar to an existing entry:

1. Search first: grep -r "keyword" .learnings/ 2. Link entries: Add See Also: SCM-20250110-001 in Metadata 3. Bump priority if issue keeps recurring 4. Consider systemic fix: Recurring supply chain issues often indicate: - Missing safety stock buffer (→ adjust policy) - Supplier concentration risk (→ qualification of alternate) - Forecast model gap (→ add decomposition or overlay) - Process gap (→ add SOP or checklist)

Periodic Review

Review .learnings/ at natural breakpoints:

When to Review

Quick Status Check

# Count pending supply chain issues
grep -h "Status\*\*: pending" .learnings/*.md | wc -l
List pending high-priority issues
grep -B5 "Priority\*\*: high" .learnings/SUPPLY_CHAIN_ISSUES.md | grep "^## \["
Find learnings for a specific area
grep -l "Area\*\*: logistics" .learnings/*.md
Find all supplier risk entries
grep -B2 "supplier_risk" .learnings/LEARNINGS.md | grep "^## \["

Review Actions

Simplify & Harden Feed

Ingest recurring supply chain patterns from simplify-and-harden into policies or playbooks.

1. For each candidate, use pattern_key as the dedupe key. 2. Search .learnings/LEARNINGS.md for existing entry: grep -n "Pattern-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+ quarters or locations, within 12-month window. Targets: supplier scorecards, safety stock policies, routing playbooks, demand models, AGENTS.md.

Hook Integration

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

Quick Setup (Claude Code / Codex)

Create .claude/settings.json in your project:

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-supply-chain/scripts/activator.sh"
      }]
    }]
  }
}

This injects a supply chain-focused learning evaluation reminder after each prompt (~50-100 tokens overhead).

Advanced Setup (With Disruption Detection)

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-supply-chain/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-supply-chain/scripts/error-detector.sh"
      }]
    }]
  }
}

Enable PostToolUse only if you want the hook to inspect command output for stockouts, delays, shortages, defects, and other supply chain disruptions.

Available Hook Scripts

| Script | Hook Type | Purpose | |--------|-----------|---------| | scripts/activator.sh | UserPromptSubmit | Reminds to evaluate supply chain learnings after tasks | | scripts/error-detector.sh | PostToolUse (Bash) | Triggers on stockouts, delays, shortages, quality issues |

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

Automatic Skill Extraction

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

Skill Extraction Criteria

| Criterion | Description | |-----------|-------------| | Recurring | Same disruption pattern in 2+ quarters or locations | | Verified | Status is resolved with effective corrective action | | Non-obvious | Required investigation or cross-functional coordination | | Broadly applicable | Not specific to one SKU or supplier; useful across categories | | User-flagged | User says "save this as a skill" or similar |

Extraction Workflow

1. Identify candidate: Learning meets extraction criteria 2. Run helper (or create manually):

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

Extraction Detection Triggers

In conversation: "This delay keeps happening", "Save this process as a skill", "Every quarter we hit this issue", "We need a standard playbook for this".

In entries: Multiple See Also links, high priority + resolved, supplier_risk or logistics_delay with broad applicability, same Pattern-Key across quarters or DCs.

Multi-Agent Support

| Agent | Activation | Detection | |-------|-----------|-----------| | Claude Code | Hooks (UserPromptSubmit, PostToolUse) | Automatic via error-detector.sh | | Codex CLI | Hooks (same pattern) | Automatic via hook scripts | | GitHub Copilot | Manual (.github/copilot-instructions.md) | Manual review | | OpenClaw | Workspace injection + inter-agent messaging | Via session tools |

Best Practices

1. Log immediately — operational context fades fast after disruption resolution 2. Quantify impact — always include units, cost, days, and service level metrics 3. Specify the supply chain node — supplier, DC, lane, or SKU family affected 4. Track lead times weekly — detect trends before they cause stockouts 5. Validate forecasts monthly — compare forecast vs. actual at SKU-family level using MAPE and bias 6. Diversify suppliers — no single-source for components with >$50K annual spend 7. Maintain safety stock — buffer by sourcing mode (ocean 3wk, air 1wk, domestic 1.5wk) 8. Inspect at receiving — verify quantity and quality before receipting into WMS 9. Document routing decisions — record why a lane or mode was chosen for future reference 10. Promote aggressively — if a pattern recurs across 2+ quarters, it deserves a policy

Gitignore Options

Keep learnings local (per-team): add .learnings/ to .gitignore. Track learnings in repo (organization-wide): don't gitignore — learnings become shared operational knowledge. Hybrid: gitignore .learnings/*.md but keep .learnings/.gitkeep.

Stackability Contract (Standalone + Multi-Skill)

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

Namespaced Logging (recommended for 2+ skills)

Required Metadata

Skill: supply-chain

Hook Arbitration (when 2+ skills are enabled)

Narrow Matcher Scope (supply-chain)

Cross-Skill Precedence

Ownership Rules

1. Log immediately — operational context fades fast after disruption resolution 2. Quantify impact — always include units, cost, days, and service level metrics 3. Specify the supply chain node — supplier, DC, lane, or SKU family affected 4. Track lead times weekly — detect trends before they cause stockouts 5. Validate forecasts monthly — compare forecast vs. actual at SKU-family level using MAPE and bias 6. Diversify suppliers — no single-source for components with >$50K annual spend 7. Maintain safety stock — buffer by sourcing mode (ocean 3wk, air 1wk, domestic 1.5wk) 8. Inspect at receiving — verify quantity and quality before receipting into WMS 9. Document routing decisions — record why a lane or mode was chosen for future reference 10. Promote aggressively — if a pattern recurs across 2+ quarters, it deserves a policy