docs: add skill build brief
This commit is contained in:
@@ -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 |
|
||||||
Reference in New Issue
Block a user