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\n**Categories**: forecast_error | supplier_risk | logistics_delay | inventory_mismatch | quality_deviation | demand_signal_shift\n**Areas**: 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

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

• LEARNINGS.md — forecast errors, supplier risks, demand signal shifts
• SUPPLY_CHAIN_ISSUES.md — stockouts, delays, quality problems, capacity breaches
• FEATURE_REQUESTS.md — supply chain tools, automation, operational capabilities

Promotion Targets

When supply chain learnings prove broadly applicable, promote them:

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:

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

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

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:

• in_progress — Actively being investigated or mitigated
• wont_fix — Accepted risk or not actionable (add reason in Resolution notes)
• promoted — Elevated to scorecard, policy, playbook, or model
• promoted_to_skill — Extracted as a reusable skill

Detection Triggers

Automatically log when you encounter:

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

• Available stock drops below reorder point
• Safety stock consumed with no inbound PO in transit
• Allocation conflict between customer orders
• WMS alerts for zero-available or negative-available

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

• Carrier tracking shows ETA pushed beyond original commitment
• Port congestion reports for origin or destination terminal
• Customs hold or inspection delay notification
• Mode conversion required (ocean → air) to meet deadline

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

• Supplier notifies of capacity reduction or allocation
• Lead time quoted on new PO exceeds historical average by >20%
• Supplier financial health downgrade (D&B, credit report)
• Force majeure notification from supplier

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

• Incoming quality inspection rejection rate exceeds 2% threshold
• Customer return rate for quality reasons exceeds 1%
• Supplier corrective action request (SCAR) issued
• Specification non-conformance on critical dimension

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

• Monthly MAPE exceeds 15% at SKU-family level
• Bias consistently positive (underforecast) or negative (overforecast) for 3+ months
• New product launch demand significantly different from analogous forecast
• Promotional lift or cannibalization not captured in model

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

• DC utilization exceeds 90% of total capacity
• Receiving dock backlog exceeds 48 hours
• Put-away queue growing faster than processing rate
• Overflow to secondary or temporary storage required

Priority Guidelines

Area Tags

Use to filter learnings by supply chain domain:

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

• Same supplier issue recurs across multiple quarters
• Forecast error pattern appears for 3+ SKU families
• Logistics delay from same lane or carrier happens 3+ times
• Quality issue at same supplier or component recurs
• Inventory mismatch pattern found in 2+ distribution centers

Promotion Targets

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

• Before finalizing replenishment plans
• After month-end demand review
• When the same disruption type appears again
• Quarterly during S&OP planning cycle

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

• Resolve mitigated issues
• Promote recurring patterns to policies and playbooks
• Link related entries across files
• Extract reusable processes as skills

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

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

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
   

3. Customize SKILL.md: Fill in template with supply chain-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 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

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)

• Namespace for this skill: .learnings/supply-chain/
• 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:

**Skill**: supply-chain

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 (supply-chain)

Only trigger this skill automatically for supply-chain signals such as:

• lead time|stockout|safety stock|supplier delay|fill rate
• forecast bias|otif|procurement|lane disruption|inventory
• explicit supply-chain 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/supply-chain/ in stackable mode.
• It may read other skill folders for cross-linking, but should not rewrite their entries.