diff --git a/references/MPM_SKU_Skill_BuildBrief.md b/references/MPM_SKU_Skill_BuildBrief.md new file mode 100644 index 0000000..fd48324 --- /dev/null +++ b/references/MPM_SKU_Skill_BuildBrief.md @@ -0,0 +1,204 @@ +# MPM SKU Skill — Build Brief +**Status:** Pre-Build / Planning Complete +**Last Updated:** 2026-05-29 +**Author:** Bryan Gilliom (via CoWork session) +**Pickup:** Resume on any CoWork system with Google Drive access to this folder + +--- + +## Purpose + +Build a CoWork skill (`mpm-sku`) that gives any Claude session — with no prior context — the ability to: + +1. **CREATE** — Given a plain-language description, produce a correctly formatted MPM part number +2. **AUDIT** — Given one or more existing part numbers, validate them against the schema and surface every structural violation (excluding UniqueID values) + +--- + +## Architecture Decision: Option A — Reference, Don't Embed + +**All taxonomy data lives in Google Drive and is read at runtime. Nothing schema-specific is locked inside the skill files.** + +This is non-negotiable because: +- 10+ CoWork users across multiple machines updating the schema +- The skill would require an update every time taxonomy changes if data were embedded +- All sessions read the same source of truth + +### What Lives IN the Skill + +| File | Contents | +|---|---| +| `SKILL.md` | Entry points, logic, decision trees, Google Drive file paths | +| `audit-rules.md` | Discrete, enumerable validation rules (logic only — no taxonomy data) | + +### What Lives in Google Drive (referenced by path) + +| File | Path | Status | +|---|---|---| +| `MPM_SKU_System_Reference.md` | `Shared drives/DOCUMENTATION/Part - Model Number and Taxonomy Information/` | ✅ Current — v1.4 | +| `MPM_SKU_Sequence_Tracker.md` | Same folder | ✅ Current | +| `MPM_SKU_Decision_Log.md` | Same folder | ❌ TO CREATE | +| `MPM_SKU_Undocumented_Subtypes.md` | Same folder | ❌ TO CREATE | + +--- + +## Files Still Needed Before Skill Build + +### 1. `MPM_SKU_Decision_Log.md` +A dated log of every taxonomy ruling made. Format: date, decision, rationale, who. This is the audit trail for why the schema is what it is. Seed it with all rulings from this session (see section below). + +### 2. `MPM_SKU_Undocumented_Subtypes.md` +A structured list of sub-types found in active use across the part number inventory that are NOT yet in the schema. Each entry needs a taxonomy decision before it can be added to the reference. Seed it with the audit findings from 2026-05-29 (see section below). + +--- + +## Open Decisions (Unresolved — Must Be Settled Before Skill Build) + +### `/YLW` vs `/YEL` — Yellow color code +- `/YLW` was added to `MPM_SKU_System_Reference.md` as the canonical code on 2026-05-29 +- The existing part number inventory ("Copy of New part number" sheet) uses `/YEL` throughout +- **Decision needed:** Is `/YLW` canonical and the sheet needs correcting? Or should the canonical code be `/YEL`? +- Until resolved: treat both as a known discrepancy; do not use either as authoritative when auditing + +### Undocumented MNT- Sub-Types +See `MPM_SKU_Undocumented_Subtypes.md` (to create). Each needs a formal taxonomy decision before being added to the schema. + +### Undocumented ACC- Sub-Types +Same — see above. + +### Solar Panel Variant Descriptors +Items in the inventory use `BIF` (bifacial), `FLX` (flexible), `RGD` (rigid) as `ACC-SLR-PNL-` variants. These are not in the schema. Need a formal descriptor pattern for solar panel sub-types. + +--- + +## Decisions Made This Session (2026-05-29) + +These are confirmed rulings — seed these into `MPM_SKU_Decision_Log.md`: + +| Decision | Detail | Rationale | +|---|---|---| +| `CLM` = Clamp | TypeSuffix `CLM` under `MNT-M-` means Clamp, not Column | Confirmed by Bryan during smoke test | +| `/GRY` is valid | Added to color code table | Gray hardware is in active use | +| `/YLW` is valid | Added to color code table as canonical yellow | Yellow hardware is in active use — but `/YEL` conflict unresolved | +| `EXD` → `EX` for components | When coding components (PRT-, FAB-, MNT-, etc.) for an EXD-family display, use `EX` + size + flags (e.g., `EX43v`) not `EXD43k` | EXD is a marketing designation; `EX43v` is the functional descriptor | +| `MPTV-EXD` retained | Display product numbers themselves (MPTV- prefix) retain EXD (e.g., `MPTV-EXD43k`) | EXD is part of the product identity at the display level | +| PA0510 burned | Do not reuse PA0510 — was assigned to KIT-PRT-SEN-EX43v, then deleted | Burned IDs are never recycled | + +--- + +## Sequence Pool State as of 2026-05-29 + +| Pool | Last Used | Next Available | +|---|---|---| +| PA (PRT-, KIT-PRT-) | PA0527 | PA0528 | +| FA (FAB-, KIT-FAB-) | FA0511 | FA0512 | +| AA (ACC-, KIT-ACC-) | AA0509 | AA0510 | +| CA (CBL-, KIT-CBL-) | CA0503 | CA0504 | +| MA (MNT-) | Not yet formally assigned under new system | MA0501 | +| SA (PKG-) | Not yet used | SA0501 | +| TA (FST-) | Not yet used | TA0501 | + +> Note: MA pool pre-v1.3 assignments exist in the inventory sheet (MA0001–MA0062 range visible) but were assigned before the x0501 starting rule. These are valid legacy numbers. New assignments begin at MA0501 to avoid conflicts. + +--- + +## Audit Findings — "Copy of New part number" Sheet (2026-05-29) + +50-item smoke test surfaced the following issue categories. Full detail in the session transcript. + +| Issue | Code | Count in 50-item sample | Description | +|---|---|---|---| +| Color suffix before UniqueID | A | 17 | `/Color` must always trail the UniqueID. Many items have it reversed. | +| Undefined color code | B | 12 | `/GRY` now valid. `/GR`, `/YEL` still invalid per schema. | +| Undocumented MNT- sub-type | C | 9 | SPC, BRC, PLT, COV, RL, DIN, ADA in active use | +| MNT-RL missing M environment segment | D | 9 | Handrails inconsistently drop the `M` — `MNT-RL-` vs `MNT-M-RL-` | +| Undocumented ACC- sub-type | E | 6+ | ADP, CPL, BOX, CLP, CAS, KEY, PRB, DRV, MIC/AMP misrouted | +| Missing UniqueID | F | 3 | Solar panels have descriptors in place of an ID — never assigned | +| Malformed pool ID | G | 1 | `A0022` missing a letter — should be `AA0022` | +| ANT sub-type combination format | H | 1 | `GPS-LTE` should be combined without hyphen: `GPSLTE` | +| Space in part number | I | 1 | `ACC-SLR-PNL- 60W-RGD-24V` has a literal space | +| Structural miscellaneous | J | 2 | Display model embedded mid-stream; unexplained `311` descriptor | + +--- + +## Undocumented Sub-Types Found in Audit (Seed for `MPM_SKU_Undocumented_Subtypes.md`) + +### MNT- Component Sub-Types (under `MNT-M-`) +| Code | Observed Meaning | Example From Sheet | Status | +|---|---|---|---| +| `SPC` | Spacer | `MNT-M-SPC-MA0013/SIL` | Needs formal taxonomy entry | +| `BRC` | Brace | `MNT-M-BRC-MA0014/SIL` | Needs formal taxonomy entry | +| `PLT` | Plate / Reinforcement Plate | `MNT-M-PLT-X-MA0016/BLK` | Needs formal taxonomy entry | +| `COV` | Cover | `MNT-M-COV-MA0019/SIL` | Needs formal taxonomy entry | +| `RL` | Rail (Handrail) | `MNT-M-RL-32mm-2000mm-MA0023/SIL` | Needs formal taxonomy entry + environment consistency rule | +| `DIN` | DIN Rail | `MNT-DIN-SLT-12IN-MA0038` | Possibly its own sub-pattern (not MNT-M-) | +| `ADA` | ADA-specific mount | `MNT-ADA-BRL/BLK-MA0057` | Possibly its own sub-pattern | + +### ACC- Sub-Types Not in Schema +| Code | Observed Meaning | Example From Sheet | Notes | +|---|---|---|---| +| `ADP` | Adapter | `ACC-ADP-HDMI-RAG-AA0027` | Right-angle, signal adapters | +| `CPL` | Coupler | `ACC-CPL-RJ45-BLK-AA0028` | Cable couplers | +| `BOX` | Junction Box | `ACC-BOX-3WY-BLK-AA0031` | Waterproof junction boxes | +| `CLP` | Clip / Cable Clamp | `ACC-CLP-P-WHT-AA0033` | P-clips, cable organizers | +| `CAS` | Case / Carrying Case | `ACC-CAS-ZIP-GRY-AA0036` | Provisioning/tool cases | +| `KEY` | Key | `ACC-KEY-TRI-SIL-AA0045` | Triangle keys, cross keys | +| `PRB` | Probe / Tool | `ACC-PRB-NDL-WDN-AA0023` | LED poke tools, maintenance tools | +| `DRV` | Drive | `ACC-DRV-FLS-USB-AA0046` | USB flash drives (vs ACC-MEM?) | +| `MIC` | Microphone (standalone) | `ACC-MIC-PNL-SIL-AA0021` | Should route through ACC-AUD-MIC per schema | +| `AMP` | Amplifier (standalone) | `ACC-AMP-160W2-24V-A0022` | Should route through ACC-AUD-Amp per schema | + +--- + +## Community Transit Project — Lessons Learned + +The EXD43k (TC-Kiosk) spare parts project (2026-05) was the first full exercise of the SKU system at scale. + +Key lessons: +- **EXD→EX for components is correct and works well.** The `EX43v` functional descriptor cleanly maps components to display family without the marketing suffix. +- **COMT/TCK client code pattern is solid.** The `[CustomerCode]/[Variant]` structure before UniqueID disambiguates customer-specific builds without polluting the top-level taxonomy. +- **Sequence tracker is essential.** Without it, ID conflicts are inevitable across sessions and users. +- **PA0510 burned** — highlights the need for a formal deletion/burn log in the tracker. +- The CT project deliverable (`CommunityTransit_EXD43k_SpareParts_MPM.xlsx`) is in the CoWork folder, not referenced by the skill. + +--- + +## Planned Skill File Structure + +``` +plugin: mpm-sku/ +├── SKILL.md ← Entry points, logic, decision trees, Google Drive file paths +└── audit-rules.md ← Discrete validation rules (logic, not data) +``` + +`SKILL.md` will reference these Google Drive files at runtime: +- `MPM_SKU_System_Reference.md` +- `MPM_SKU_Sequence_Tracker.md` +- `MPM_SKU_Decision_Log.md` +- `MPM_SKU_Undocumented_Subtypes.md` + +--- + +## Nuance Still To Add Before Skill Build + +- [ ] Resolve `/YLW` vs `/YEL` +- [ ] Formal taxonomy decisions on all undocumented MNT- sub-types +- [ ] Formal taxonomy decisions on all undocumented ACC- sub-types +- [ ] Solar panel variant descriptor pattern (BIF, FLX, RGD) +- [ ] AUDIT mode issue category definitions (A through J from this session are a good starting point) +- [ ] Rule: how the skill handles "unknown sub-type" — prompt for taxonomy decision vs. flag and continue +- [ ] Rule: how the skill handles sequence assignment — read-then-increment vs. user confirms before committing +- [ ] Rule: batch audit behavior — stop on first error or surface all issues +- [ ] MNT-RL environment consistency rule — is `MNT-M-RL-` correct or is a different sub-pattern needed? +- [ ] DRV vs MEM distinction — are USB flash drives ACC-DRV or ACC-MEM-USB? +- [ ] HRN (Horn) observed in `ACC-ADA-2e-SPK-HRN/BLK-AA0015` — is this a valid ADA variant? +- [ ] BRL (Braille) observed in `ACC-ADA-1e-BRL/BLK-AA0014` — is this a valid ADA variant or goes through a different field? + +--- + +## Reference Sheet URLs + +| Sheet | URL | +|---|---| +| Revised - Simplified SKU System | https://docs.google.com/spreadsheets/d/1UIUx5BDbcyKHUnRnVtjKpWBOv_IFLJX0K31WHzpxX6Q/edit | +| Copy of New part number (inventory) | https://docs.google.com/spreadsheets/d/1S2Ftpl19vioHVo6Zl6tX_rX2g8gQXsM34XI2beoVRuY/edit |