---
name: competency_framework_design
description: "Build a competency framework for a team or role family: pick competencies from real work evidence, write proficiency levels that raters can tell apart, map roles to required levels, and validate the model against hiring, review, and training use. Use when creating or fixing a competency framework, proficiency matrix, skills matrix, career level guide, or role profile set, or when existing levels are too vague to rate against."
---

# Competency Framework Design

## Purpose

Build a framework that holds up in three hard moments: a hiring panel scoring a candidate, a manager defending a review rating, and a trainer turning a gap into a learning objective. Most frameworks fail before those moments. They list traits instead of work, write levels that differ only in adverbs, and map every senior title higher on everything. This skill prevents that by starting from work evidence, writing levels against shared differentiators, and validating the draft before it ships.

Two reference models show the shape. SFIA defines seven levels of responsibility once for its whole framework, separated by five generic attributes: autonomy, influence, complexity, knowledge, and business skills. SHRM defines each competency with a definition, subcompetencies, behaviours, and proficiency standards across four career levels. Copy the discipline, not the content. A framework has to describe this team's work.

## Workflow

### 1. Fix the scope and the uses first

- Name one role family, not the whole company. A family shares work: support specialists and their leads, backend engineers, field technicians. Frameworks built for everyone describe no one's work well.
- List the roles in the family and the duties each role actually carries. Use current job descriptions as a starting point only, then correct them against real work in step 2.
- Declare the uses, in priority order: hiring, review, promotion, training, pay, or workforce planning. Write the order down. It decides later arguments. A framework used for pay and promotion needs tighter validation than one used only to plan training.
- Agree who owns the framework after it ships and when it gets reviewed. A framework with no owner drifts while decisions keep citing it.

### 2. Gather work evidence before naming any competency

Collect at least two of these sources, and record which ones were used:

- Critical incidents: ask people who know the work for specific stories where someone's behaviour made a job go clearly well or clearly badly. Record the situation, the behaviour, and the result. This is the Critical Incident Technique, set out by Flanagan in 1954, built to identify the behaviours that separate success from failure in a specific job. Vague praise ("she is great with customers") is not an incident. Push for the story.
- Work samples and artefacts: tickets, cases, documents, code reviews, call recordings, project plans. Sort a sample of recent work into the kinds of work it actually contains.
- Task and duty records: existing rubrics, quality scorecards, escalation logs, onboarding checklists. Escalation logs are especially useful, because they show where one role's work ends and the next role's begins.
- External taxonomies as a cross-check, not a source: O*NET separates knowledge, skills, abilities, work activities, and tasks for occupations, and ESCO marks skills as essential or optional for an occupation. Use them to spot a competency the internal evidence missed, then confirm it exists in this team's work before adding it.

Stop when new incidents mostly repeat kinds of work already collected. That point, not a fixed count, is the signal the evidence covers the job.

### 3. Cluster evidence into competencies

- Group incidents and work samples by the work being done, not by the person doing it. Each cluster that is distinct, observable, and matters to outcomes is a candidate competency.
- Give each competency: a short name, a one or two sentence definition in plain language, and the duties it traces back to. A competency that traces to no duty gets cut.
- Separate knowledge, skill, and behaviour inside the definition where it helps raters. ESCO makes the same split, distinguishing knowledge concepts from skill and competence concepts. Raters assess knowledge differently from observed behaviour, and mixing them in one anchor confuses both ratings.
- Keep the set small enough to rate in a real conversation. Working rule: 5 to 9 competencies per family. Above that, panels skim and reviews turn into form filling. Merge clusters that share the same evidence.
- Cut any candidate that cannot be anchored separately. If its observable behaviours already live inside another competency, keeping it double-counts the same evidence. The worked example in `references/worked-example-support.md` shows this cut being made for a real candidate.

### 4. Define the level scale once, for the whole framework

- Pick the number of levels before writing any anchor. Working rule: start with four. Add a level only when a real role sits between two levels and raters keep splitting the difference. See `references/level-writing-rules.md` for the reasoning and for how SFIA and SHRM set their scales.
- Write a short generic definition for each level, covering scope, autonomy, and consequence if the work goes wrong. Example shape: level 1 does set work under direction, level 2 does the full standard work independently, level 3 handles the hard end of the range and work others rely on, level 4 sets the standard and changes the system the work runs in.
- Keep one scale across all competencies in the family. Different level counts per competency are allowed only when the work truly differs, and the validator flags them so the choice stays deliberate.

### 5. Write the anchors, one level at a time

- Write anchors competency by competency, all levels in one sitting, so the progression stays visible.
- Follow the anchor formula and the banned patterns in `references/level-writing-rules.md`: action verb, object, context, standard. Every anchor must name evidence a rater could look at.
- Make adjacent levels differ on at least one real differentiator: autonomy, complexity, influence, knowledge in use, or scope of consequence. If the only change is an adverb, rewrite.
- Write level 1 as competent work under direction, not as a list of failures. People enter at level 1, and the framework should describe work they can be proud of doing well.
- Write the top level as it actually works in that competency. In some competencies the top level is mastery of hard cases. In others it is owning the standard, the rubric, or the backlog. Do not force one pattern onto every competency.
- Run the three swap tests from the level-writing rules (blind sort, adjacent swap, evidence test) before moving on.

### 6. Map roles to required levels

- Build the mapping as a matrix: one row per role and competency pair, with the required level and an essential flag. Use the format in `references/example-mapping-support.csv`.
- Map duties, not rank. For each cell, name the duty that needs that level. If no duty needs it, lower the cell. The most common mapping error is the most senior title scoring highest on everything, including work the role no longer does.
- Use the essential flag the way ESCO uses it: essential means the competency at that level is usually required for the role regardless of team or context, optional means it depends on the current assignment. Hiring panels treat essential gaps and optional gaps differently, and the flag is what lets them.
- Check the matrix for shape: a role mapped far above similar roles needs a duty-based reason, and a competency required at the top level for every role probably has its levels written too low.

### 7. Validate before rollout

Run the protocol in `references/validation-protocol.md`. In short:

- Content check by retranslation: people who know the work but did not draft the anchors sort shuffled anchors back into competency and level. Anchors that land in the wrong place get rewritten or cut.
- Rater check: two raters score the same people independently from evidence. Investigate every spread, and fix the cause (evidence pack, anchor wording, or mapping) rather than averaging the scores away.
- One live trial per declared use: one hiring scorecard, one small review cycle, one training objective built from a gap. A framework that was never tried in its declared use is not validated.
- Fairness read: rewrite any anchor that could be rated on personal style, accent, background, or working pattern instead of behaviour and output.
- Fill in the validation record from the protocol and set the next review date.

### 8. Check the files mechanically, then ship the pack

- Put the framework in CSV form (columns: competency, level, anchor) and the mapping in CSV form (columns: role, competency, required_level, essential). Quote any field that contains a comma.
- Run the validator: `python3 scripts/validate_framework.py framework.csv --mapping mapping.csv`. Fix every error. Read every warning and either fix it or write down why it stands.
- Ship the pack listed in the Output Contract, with the validation record filled in, not promised for later.

## Output Contract

Deliver all of these:

- Framework document: family scope, roles covered, declared uses in priority order, owner, review date.
- Competency set: for each competency, name, plain definition, the duties it traces to.
- Level scale: the generic definition of each level, written once for the whole framework.
- Anchor matrix: every competency written at every level, in CSV form that passes the validator.
- Role mapping: required level and essential flag per role and competency, in CSV form, each high cell traceable to a duty.
- Validation record: content check, rater check, one trial per declared use, fairness read, and the changes each check produced.
- Gap guide: one short section telling readers what a one-level gap, a multi-competency gap, and an above-requirement profile each call for, so managers do not improvise the meaning of a gap.

## Operating Rules

- Evidence before headings. No competency enters the framework from a brainstorm alone. It needs incidents, work samples, or records behind it.
- Rate behaviour and output, never traits or personal style. If an anchor could be used to rate someone's personality, rewrite it.
- Job-related only. Every anchor and every mapping cell must trace to a duty of a role in the family. This keeps the framework defensible when it informs hiring or promotion. This skill is a design method, not legal advice.
- One framework, one scale, one owner. Forks and private variants destroy the shared language the framework exists to create. Changes go through the owner and get a new version note.
- Small and finished beats large and drafted. A 6 competency framework that passed validation is worth more than a 20 competency model nobody tested.
- Numbers given as working rules in this skill (competency count, level count, sorting threshold, review cadence) are practical starting choices for the method. They are not findings from SFIA, SHRM, O*NET, or ESCO, and the skill does not present them as such.
- Do not copy SFIA, SHRM, O*NET, or ESCO content into a framework wholesale. Their structures are references. Their text belongs to them, and a copied competency describes their occupation model, not this team's work.