gd-aging-analysis

Aging Analysis Skill

What This Skill Does

Aging Analysis is the weekly read-only Skill that answers one question for the finance, planning, and merchandising leadership team every Monday morning: is inventory turning the way we want, and where is cash trapped?

It surfaces:

• Aged inventory by cohort — baseline view per Warehouse Location, 90+/180+/365+ day cohorts
• Stale Lot Risk — lots stuck in Reserved, Unsellable, or one Channel while newer lots flow around them; with FIFO two-transfer swap recommendations
• Dead stock — SKUs that aren't moving at all
• Inventory turnover scorecard — per-Location actual vs target turnover, with trend

This Skill does not draft transfers. For Stale Lot Risk findings, it surfaces the required transfer order the user must follow when running transfers in the GoodDay UI or via gd-rebalance / gd-safety-stock. The FIFO order is critical — running transfers in the wrong order causes the stuck lot to boomerang right back where it came from.

Before You Start

1. Read the shared launch configuration: ../Configuration — Shared.md — schedule, delivery, output shape, Location classification table (Warehouse vs Retail Store), annual inventory turnover target, Data Source contract (Section 16).
2. Read this Skill's configuration: ./Configuration - Aging Analysis.md — cohorts, threshold multipliers, bypass-buffer rules, wholesale inclusion, ignore lists.
3. Read the SOP: ./SOP - Aging Analysis.md — full procedure, FIFO two-transfer logic, sub-type classifications.
4. Apply the Brand Guide: ../🖼️ Brand Guidelines.pdf.
5. Resolve data source per the Data Source section below.
6. Verify Warehouse Location list from the shared Location classification table. Retail Store and Other classifications are excluded.

Data Source

This Skill describes the business entities each routine needs. The concrete mapping — which MCP tool, verified query, or CSV column populates each entity — lives in ../MCP Tool Catalog.md. When the GoodDay MCP renames a tool or publishes a new verified query, only the catalog changes; this Skill does not.

Session context comes from the connected MCP's standard surface; filter all results to Warehouse-classified Locations.

Entities this Skill needs — look each one up in the catalog:

Routine	Entity needed
1 — Aged Inventory by Cohort	Aged lots per Warehouse Location organized into the configured cohort boundaries
2 — Stale Lot Risk	Lot positions across Channels and States for sub-type A (Reserved bypass), sub-type B (Unsellable stale), sub-type C (Cross-Channel stranded), plus the bypass-buffer signal for sub-types A and C
2 — Cost-trend delta (supplementary)	Lot-grain inventory valuation + most recent landed cost for the SKU
2 — Sub-type B context	Write-off / scrap adjustment history
3 — Dead Stock Watch	SKUs at Warehouse Locations with zero fulfillments in the configured trailing turn period
4 — Inventory Turnover Scorecard	Per-Location trailing-window units fulfilled and average on-hand
All — Movement history cross-reference	Per-SKU inventory activity over a date range

Output delivery and drill links per ../Configuration — Shared.md and per-row deep_link.

Catalog binding may be partial. If the catalog's current binding for any entity returns VALIDATION_ERROR: not_found, follow ../Configuration — Shared.md Section 12b. This Skill carries the heaviest analytical dependency in the set; routines that depend on a missing verified query surface a notice and skip rather than guessing.

Schedule

This Skill runs Monday 6am USA Central, weekly — overriding the daily-weekday default in the launch set. Ad hoc invocations are always available.

Turnover-driven thresholds

This Skill derives most day-thresholds from the merchant's configured turnover target:

threshold_days = 365 / (target_turnover × multiplier)

At the default 4x target:

• Unsellable stale: ~180 days (multiplier 0.5)
• Reserved + Channel stuck: ~120 days (multiplier 0.75)
• Dead stock: ~91 days = ~13 weeks (multiplier 1.0)

When target changes, thresholds scale automatically.

Workflow

Routine 1: Aged Inventory by Cohort   → 90/180/365-day cohorts per Warehouse Location
Routine 2: Stale Lot Risk             → 3 sub-types: Reserved / Unsellable / Cross-Channel
                                        Bypass-buffer signal for A and C
                                        FIFO two-transfer recommendations
Routine 3: Dead Stock Watch           → SKUs with zero fulfillments in trailing turn period
Routine 4: Inventory Turnover Scorecard → Per-Location actual vs target
Scorecard: aging-scorecard            → Severity-scored roll-up of all four

Routine 1 — Aged Inventory by Cohort

Pull all lots beyond the aging baseline (90 days), organized into 90+/180+/365+ day cohorts. Per Warehouse Location only — no cross-Location aggregation. Attach persistent flag for lots in the same cohort across 3 of last 5 weekly runs without movement.

Routine 2 — Stale Lot Risk

For each Warehouse Location, scan across Channels and States for three sub-types:

• Sub-type A — Stranded in Reserved: At each SKU + Channel + Location, find lots in Reserved older than the Reserved+Channel threshold (~120d default at 4x target) with a newer lot in Available at the same SKU+Channel+Location.
• Sub-type B — Stranded in Unsellable: At each SKU + Channel + Location, find lots in Unsellable older than the Unsellable threshold (~180d default at 4x target).
• Sub-type C — Cross-Channel Stranded: At each SKU + Location, find lots in one Channel older than the Reserved+Channel threshold with a newer lot in another Channel at the same SKU+Location.

For sub-types A and C, layer the bypass-buffer signal: examine the last 10 fulfillments for the SKU at the Location; raise the flag if >80% went to a newer lot. If fewer than 10 fulfillments exist in the window, do not raise the flag.

For each finding, classify the likely cause (operational vs ledger-logic) for human review. Surface the cost-trend delta (stuck lot cost vs most recent landed cost for the SKU) as supplementary context — not part of severity.

Recommended action — FIFO two-transfer swap (critical). The Skill produces recommendations but does NOT draft transfers. The recommended transfer order is non-negotiable because virtual transfers apply FIFO at origin — the oldest lot is moved first. Naive single transfers will boomerang the stuck lot back.

• Sub-type A swap option: (1) Transfer IN to Reserved (Available → Reserved) — FIFO pulls newer Available lot. (2) Transfer OUT of Reserved (Reserved → Available) — FIFO pulls oldest = stuck old lot. Stuck lot lands in Available and finally flows through fulfillment.
• Sub-type A simple-release option: Single Reserved → Available transfer. Stuck lot exits; Reserved buffer reduced.
• Sub-type C consolidation option: Single transfer from stale Channel → active Channel. FIFO pulls oldest = stuck lot.
• Sub-type C channel-swap option: (1) Transfer IN to stale Channel (active → stale Channel) — FIFO pulls newer lot from active Channel. (2) Transfer OUT of stale Channel (stale → active Channel) — FIFO pulls oldest = stuck lot.
• Sub-type B: No swap. Recommend write-off Adjustment with appropriate reason + disposition decision (vendor return / donation / disposal).

Surface both options for A and C; let the user decide based on whether they want to maintain the Reserved buffer or Channel inventory balance.

Routine 3 — Dead Stock Watch

For each SKU at each Warehouse Location with positive on-hand, count fulfillments in the trailing 13 weeks (default — derived from turnover target). If zero, flag as dead stock candidate. Tag persistent if flagged in 3 of last 5 weekly runs.

Routine 4 — Inventory Turnover Scorecard

For each Warehouse Location, compute trailing-360-day turnover: units_fulfilled / average_on_hand_units. Compare to merchant's configured target. Compute trend by comparing first 180 days vs last 180 days of the window. Include Wholesale by default; respect merchant config if excluded.

Aggregate across Locations; identify which Locations are dragging the average (default: actual turnover under target by 25%+).

Scorecard — aging-scorecard

Read outputs of Routines 1–4. Do not re-detect. Apply the severity rules defined in ./Configuration - Aging Analysis.md (Severity thresholds section). Compose the headline ("Is inventory turning the way we want?"), top-10 punch list across all routines, tail summary, and routine-by-routine detail per the shared Output shape (../Configuration — Shared.md Section 7).

Output

Follow the output shape from the shared Configuration:

• Headline — severity badge + total $ trapped + Locations below target + key callouts
• Scorecard punch list — top-10 across all routines, ranked by $ trapped + age
• Tail line — +N more lines totaling $X if more than 10
• Detail by routine — as outlined in the SOP, with FIFO two-transfer recommendations prominently displayed for Stale Lot Risk findings
• Persistent issues — cross-routine view
• Temporarily ignored — visibility section

Render against the GoodDay Brand Guide. Post to the configured Slack channel for scheduled runs.

Caveats to Always Include

1. FIFO order on virtual transfers is non-negotiable. Surface the required transfer order prominently for every Stale Lot Risk recommendation. Reversing the order boomerangs the stuck lot back into the state it left. The Skill does not draft transfers — the user runs them in the GoodDay UI or via gd-rebalance / gd-safety-stock, and the order is the user's responsibility to execute correctly.
2. This Skill recommends, does not draft. Transfer drafting lives in the action Skills.
3. Per-Location scoping is strict. No cross-Location aggregation for Stale Lot Risk or Dead Stock Watch. Inventory at different Warehouse Locations is physically different inventory.
4. Warehouse Locations only. Retail Stores excluded via the shared Location classification table.
5. Wholesale's lumpiness can distort turnover. Default is to include Wholesale; merchants can exclude per configuration.
6. Cost-trend delta is supplementary. Surfaced as context for the controller but does not raise severity. Severity is driven by days, units, and turnover deviation.

Edge Cases

• SKU with <10 fulfillments in the rolling window: Do not raise bypass-buffer flag (this is the correct behavior — too little activity to evaluate, and a SKU with low velocity may legitimately have languishing lots).
• Lot age just under threshold: Don't surface yet. Let normal turnover happen.
• Stuck lot in a SKU with no current landed cost: Surface the stale-lot finding without the cost-trend delta. Flag the missing cost data — likely a gd-costing-quality issue too.
• Location classified as Other in shared config: Excluded from this Skill. Surfaced in a footnote so the user knows the Location was intentionally skipped.
• Zero findings in a routine: Report "None found — this is what healthy looks like" rather than omitting the section.
• Newly added Warehouse Location with <360 days of history: Calculate turnover on whatever history exists, but flag the short window and exclude from cross-Location aggregate until 360 days of history accrue.