# Skill Management — Feature & Functionality Guide

**Purpose of this document:** a single, code-grounded source of truth for everything the **Skill
Management** module does today in GB5, organized so sections can be lifted directly into
audience-specific deliverables — developer reference, implementation/config guide, admin guide,
end-user help, and marketing/sales collateral. Every claim below is grounded in the actual backend
(`GB5Solution/SkillManagement`) and frontend (`gb4.7mfe/projects/skillmanagement`) code as of
2026-08-20. Sections marked **[Internal only — not for marketing]** describe known gaps and should
not appear in customer-facing material.

**Module boundary:** Skill Management is a standalone 3-tier module
(`SkillManagementSL`/`SkillManagementBLL`/`SkillManagementDAL`), architecturally separate from the
**Work Instruction (WI)** module (`WiSL`/`WiBLL`/`WiDAL`) — separate backend project tree, separate
Angular federation frontend project, separate Dapr sidecar. The two integrate, but do not share
code: Work Instruction *reads* Skill Management's skill/employee-skill data (to gate execution and
compute skill gaps), and TMS (Training Management) *writes into* Skill Management's employee skill
profile via one Dapr event. Everything workstation, line, roster, scan-code, digital-twin, and
Work-Instruction-authoring related lives in the separate **Work Instruction** module — see
`Docs/WorkInstruction-Feature-Functionality-Guide.md` for that side. TMS's own training/assessment
functionality is documented in `Docs/TMS-Feature-Functionality-Guide.md`.

---

## 1. Executive Summary (marketing/sales-friendly)

GB5 Skill Management defines the skills, levels, and domains an organization cares about, and tracks
every employee's current proficiency against them — a live, queryable skills record rather than a
spreadsheet that goes stale the day it's exported. Skills can be organized by domain/group,
linked to the product families and process/routing stages they apply to, and rolled up into
job-role skill requirements, so an organization can define not just "what skills exist" but "what
this job actually requires."

The standout differentiator is the closed loop with Training (TMS): when an employee passes a
mapped assessment or completes a mapped training programme, GB5 can automatically raise their
recorded skill level — with human review where a client wants it — so the skills database reflects
verified reality without manual re-entry. A configurable **Skill Matrix** gives HR and line
management a live, drillable wall-chart view of who knows what, and this same skill data is what
powers the shop-floor execution controls and readiness dashboards in the companion Work Instruction
module.

---

## 2. Functional Area Catalog

### 2.1 Skill Master Data
- **Skill**, **Skill Group**, **Skill Domain**, **Skill Level** — the core taxonomy: every skill
  belongs to a group, every group to a domain, and every skill has a defined set of proficiency
  levels.
- **Skill–Product Map** — links skills to product families/models, so skill requirements can be
  derived from what's being built.
- **Skill–Process Stage Map** — links skills to routing/process stages, tying a skill directly to a
  manufacturing operation.
- All master data is standard admin-configurable CRUD (grid + form), with dropdown/select-list
  endpoints for use throughout the platform.

### 2.2 Role/Job Skill Requirement
- Defines the skill(s), minimum level, and category (Core / Technical / Specialist / Optional) a
  job role requires — the baseline against which individual and team skill gaps are measured
  (both within this module's Skill Matrix, and downstream in Work Instruction's eligibility and
  gap-analysis features).

### 2.3 Employee Skill Profile
- The living record of what each employee can actually do: current skill, current level (0–4),
  and a profile status (0–3, e.g. Draft/Current/Superseded).
- **Manual maintenance** — HR/line supervisors can save or bulk-save an employee's skill profile
  directly. Bulk save resolves a level given by name or by number and safely dedupes repeated
  entries within the same batch.
- **Automatic maintenance** — see §2.6: profile rows written by the TMS integration are tagged with
  a distinct source (system/auto vs. human-assessed) so the origin of every skill record is always
  traceable, and an automatic update never silently downgrades a higher level a human already
  verified.
- Full history is queryable per employee.

### 2.4 Skill Assessment
- A manual, human-assessor workflow, separate from the automated TMS path: record an assessment
  (method: 6 supported types), the level achieved, and the assessor.
- Automatically captures the employee's *previous* level at the moment of assessment — a genuine
  before/after audit trail, not just a point-in-time snapshot — and writes the new level through to
  the employee's live Skill Profile as the current record.
- Full assessment history is browsable per employee.

### 2.5 Skill Matrix
- A configurable, saved-view grid: rows/columns of employees × skills (optionally filtered by
  department, job role, or process routing), each cell showing the employee's current level at a
  glance — the classic "skills matrix" wall-chart, live and drillable.
- **Skill Matrix Config** — save named matrix layouts (which skills/departments to include) so
  different teams or shifts can have their own saved view rather than rebuilding filters every time.
- Drill-in on any cell for full detail on that employee/skill pairing (assessment history, current
  vs. required level).

### 2.6 Automatic Skill-Level Upgrades (flagship cross-module integration)
- When an employee passes a mapped assessment or completes a mapped training programme in TMS,
  TMS resolves the most specific applicable skill mapping and proposes a skill-level upgrade —
  either auto-approved or held for manager review (Approve/Reject, with a recorded reason on
  rejection), depending on how the programme is configured. This proposal/review workflow lives in
  TMS — see `Docs/TMS-Feature-Functionality-Guide.md` §2.9 for that side.
- On approval, TMS publishes a Dapr pub/sub event (`tms.skillgrant.confirmed`) that Skill
  Management's `TmsSkillGrantSubscriber` picks up and applies directly to the employee's live Skill
  Profile via `SkillGrantBLL.ApplySkillGrantAsync` — **never auto-downgrading** an already-higher
  level a human previously verified, and always tagged as a system/auto-sourced record so it's
  distinguishable from a manually recorded assessment (§2.4).
- This is the mechanism that keeps the organization-wide skills record synchronized with actual,
  verified training/assessment outcomes — closing the loop between "we identified a skill gap" and
  "the system record now reflects the employee is qualified," without manual re-entry. It is also
  the one and only integration point where Skill Management calls out to another module at runtime.

### 2.7 Skill-Gap-Driven Training Need Creation (generalized producer mechanism, added 2026-08-20)
- Complements §2.6's TMS→Skill Management direction with the reverse flow: a detected skill gap can
  now automatically raise a TMS Training Need, not just receive a training outcome.
- TMS exposes a generalized, non-interactive entry point, `ITrainingNeedBLL.ProposeTrainingNeed`,
  built specifically so *any* producer module — Skill Gap today, PMS/OKR/Quality potentially in
  future — can raise a need programmatically (tagged with its own `NeedSourceType` and a
  `SourceRefEntity`/`SourceRefId` pointer back to the triggering record) without going through the
  UI-form-shaped `SaveTrainingNeed` path. It's idempotent — repeated calls for the same source record
  return the existing open need rather than creating duplicates — and non-fatal to whatever
  triggered it.
- The concrete, real producer wired end-to-end today: Work Instruction's roster Skill Gap screen has
  a "Raise Training Needs for Gaps" action (`WiSkillGapBLL.RaiseTrainingNeedsForRosterGaps`) that
  publishes a Dapr event per Warn/Block-enforcement gap it finds; a new TMS subscriber
  (`TMSSL/Subscriptions/WiSkillGapSubscriber.cs`) upserts the previously-unwired `TSKILLGAPLINK`
  bridge table and calls `ProposeTrainingNeed` for High/Critical-severity gaps — see the Work
  Instruction guide's §2.6 and the TMS guide's own notes on this integration for the full mechanics.
- This module's own role in the flow is receiving the eventual outcome: once a Training Need drives a
  training programme to completion, §2.6's existing skill-upgrade path closes the loop back into the
  Employee Skill Profile — the same integration this section's producer feeds *into* TMS.

---

## 3. For Developers

- **Backend layout**: `GB5Solution/SkillManagement/{SkillManagementSL,SkillManagementBLL,
  SkillManagementDAL}`, the standard GB5 3-tier convention (FastEndpoints / BLL / Dapper). Its Dapr
  sidecar config (`pubsub.yaml`, `statestore.yaml`, `timer.yaml`, `tracing.yaml`, `vault.yaml`)
  lives under `SkillManagementSL/components/`.
- **The one inbound cross-module wire**: `SkillManagementSL/Subscriptions/TmsSkillGrantSubscriber.cs`
  subscribes to Dapr pub/sub topic `tms.skillgrant.confirmed` (published from
  `GB5Solution/TMS/TMSBLL/TxSkillUpgrade/TxSkillUpgradeBLL.cs`) and calls
  `SkillManagementBLL/SkillGrant/SkillGrantBLL.ApplySkillGrantAsync`. Everything else in this module
  is self-contained CRUD/read logic with no outbound calls to WI or TMS.
- **Work Instruction reads from here, doesn't own anything here**: the WI module (separate codebase,
  see its own guide) queries `MEMPLOYEESKILLPROFILE`/`MSKILL`/`MSKILLLEVEL` etc. directly for
  eligibility evaluation and skill-gap computation — there is no API call from WI into
  SkillManagementSL; both read the same underlying tables. Keep this in mind when changing the skill
  profile schema: WI's `WiExecutionBLL` and skill-gap DAL queries depend on its shape even though
  they live in a different project.
- **Real-time push (added 2026-08-20)**: `SkillManagementSL/EndPoints/Hubs/SkillHub.cs`
  (`Hub<ISkillHubClient>`, mapped at `/hubs/skill`) plus `SkillManagementBLL.Common.ISkillHubNotifier`
  / `SkillManagementSL/EndPoints/Hubs/SkillHubNotifier.cs` — the same BLL-decoupled
  `IHubContext`-wrapper pattern as WI's `WiHub`/`IWiHubNotifier`. Wired into
  `EmployeeSkillProfileBLL.Save`/`BulkSave` and `SkillAssessmentBLL.Save` (and therefore
  `SkillGrantBLL.ApplySkillGrantAsync`, which delegates into `EmployeeSkillProfileBLL.Save`) — every
  path that touches `MEMPLOYEESKILLPROFILE` pushes a `ReceiveProfileChanged`/`ReceiveMatrixChanged`
  ping. Payloads carry no data (client re-fetches on receipt), same "ping, not a data carrier" design
  as `IWiHubClient`. Client joins `SkillHub.EmployeeGroup(employeeId)` to watch one employee or
  `SkillHub.MatrixGroup(clientId)` to watch the whole tenant's Skill Matrix.
- **Route naming fixed (2026-08-20)**: `RoleSkillRequirement`'s three GET-by-filter endpoints now
  live consistently under `/RoleSkillRequirement/*` — `GetRoleSkillRequirementByRole` (the one
  actually used by the FE, previously at the mismatched `/RoleRequirement/GetRoleRequirement`),
  `GetRoleSkillRequirementById`, and `GetRoleSkillRequirementBySkill` (previously the typo'd
  `/RoleSkillRequiremet/GetRoleSkillRequiremet` — no frontend caller either way). The FE's
  `Skill.Roleskillrequirement.Get` route key was updated to match.
- **Schema churn to be aware of**: `MEMPLOYEESKILLPROFILE` replaced an older `MEMPLOYEESKILL` table
  very recently (2026-08-06); the rollback script for the old table notes the original column shapes
  were not fully recoverable. Verify the live schema directly before writing new code against
  employee-skill tables rather than trusting an older reference.
- **Frontend layout**: `gb4.7mfe/projects/skillmanagement/**`, an Angular native-federation
  micro-frontend with an intentionally empty `app.routes.ts` — routing is resolved by the host shell
  from `MWEBFORM.WEBFORMSECONDURL` menu rows at runtime, not by an Angular router config in the
  sub-app. A component only becomes reachable once its `MMENU`/`MWEBFORM` rows exist.

---

## 4. For Implementers / Admins — What's Configurable

Configurable today through the UI: the full skill taxonomy (Skill / Skill Group / Skill Domain /
Skill Level), Skill–Product and Skill–Process Stage mappings, Role/Job Skill Requirements, Skill
Matrix configurations (saved views), manual Skill Assessments, and TMS's skill-map configuration
that drives automatic upgrades (configured on the TMS side, applied here — see §2.6).

Hardcoded (not admin-configurable via UI): skill level count/numbering (0–4), profile status
enumeration (0–3), and assessment method taxonomy — these are code-level constants, changed only by
a developer.

**A note for go-live planning**: this module's data is a dependency for Work Instruction's
execution-gating and skill-gap features — populate skill master data, role requirements, and
employee skill profiles *before* configuring WI enforcement rules, or every WI eligibility check
will simply fail to find data.

---

## 5. For End Users — Roles & Journeys

- **Employee**: view their own current skill profile and assessment history.
- **HR / Skill Administrator**: maintain the skill taxonomy and role skill requirements, manage
  employee skill profiles and manual assessments, configure the skill matrix, and review pending
  automatic skill-upgrade proposals originating from TMS.
- **Line Supervisor / Team Lead**: use the Skill Matrix to see team skill coverage at a glance; this
  same data feeds the roster/staffing readiness views in the Work Instruction module.
- **Manager**: approve/reject automatic skill-upgrade proposals for direct reports (workflow itself
  lives in TMS; the effect lands here).

---

## 6. For Marketing / Sales

Lead with what's real, working, and differentiated:
- A live, structured skills database — not a spreadsheet — with a full taxonomy (domain → group →
  skill → level) that ties directly to products and process/routing stages, so skill requirements
  are derived from real operational structure, not typed in free-hand.
- **Automatic skill-record upgrades on training success**, shared with TMS, is the standout,
  hard-to-copy capability — training and assessment outcomes flow straight into the live skills
  record, with human review where it matters.
- A configurable, drillable **Skill Matrix** wall-chart view, replacing static spreadsheets teams
  currently maintain by hand.
- This module is the data foundation for GB5's shop-floor execution controls (Work Instruction
  skill-gating, roster readiness, digital twin) — position it as the "single source of truth" that
  those visible, operational features are built on.
- **The loop now genuinely closes both ways**: training success flows into the live skills record
  (§2.6), and a detected skill gap can flow back out as an automatically-raised Training Need (§2.7)
  — a real, wired, bidirectional connection between "skills we track" and "training we run," not just
  one direction.
- Real-time push (Skill Matrix, Employee Profile) landed 2026-08-20 — safe to describe as live/
  push-based now, not just fast-refreshing.
- **Do not yet promise**: automatic Training-Need-raising from every possible source — only Skill
  Gap (via Work Instruction) is wired end-to-end today; Appraisal/OKR/Quality-driven auto-raise would
  need those modules to build their own gap/need-detection logic first (the generalized
  `ProposeTrainingNeed` receiving side is ready for them, but they don't produce events yet) — see §7.

---

## 7. Known Gaps / Roadmap Items — [Internal only, not for marketing]

| Area | Status |
|---|---|
| `MEMPLOYEESKILLPROFILE` schema stability | Replaced the older `MEMPLOYEESKILL` table very recently (2026-08-06); the predecessor's exact original column shapes are not fully recoverable per the rollback script's own notes. Treat as recently stabilized — verify the live schema before building new integrations against it. |
| Skill-gap-driven Training Need creation — partial | **Fixed for Skill Gap specifically** (2026-08-20): Work Instruction's roster gap screen can now auto-raise a TMS Training Need via the new generalized `ITrainingNeedBLL.ProposeTrainingNeed` + a `wi.skillgap.detected` Dapr event + TMS's `WiSkillGapSubscriber`. Appraisal/OKR/Quality-driven auto-raise still needs those modules to build their own producing/detection logic — the receiving mechanism is generalized and ready, but only one real producer exists today. Not yet browser/live-verified end-to-end on a running environment. |
| `ProposeTrainingNeed`'s Training Domain requirement | `TTRAININGNEED.TRAININGDOMAINID` is `NOT NULL` with a hard FK to `MTRAININGDOMAIN`, which has no seeded rows anywhere in the repo — it's pure tenant-configured master data. A tenant with zero configured Training Domains will have every auto-raise attempt fail validation (non-fatally — the underlying Skill Gap record still saves) until an admin configures at least one domain. Flag this as a go-live prerequisite for any client wanting this feature. |

Previously listed here and now resolved (2026-08-20): `RoleSkillRequirement` route naming (all three
GET-by-filter endpoints now live consistently under `/RoleSkillRequirement/*`, typo fixed) and "no
real-time push" (SignalR hub added for Skill Matrix/Employee Profile) — see §3 for details on both.

---

*Compiled from a live code audit of `GB5Solution/SkillManagement` and
`gb4.7mfe/projects/skillmanagement` on 2026-08-20. See `Docs/WorkInstruction-Feature-Functionality-
Guide.md` for the companion module that consumes this data on the shop floor, and
`Docs/TMS-Feature-Functionality-Guide.md` for the training/assessment side of §2.6's integration.
Re-verify dated items (§7) against current code/DB state before relying on them in a live client
conversation.*