Capability — Declared, Learned, and Reinforced

The fixed nine-skill vocabulary

Kavanah uses a closed vocabulary of nine canonical skills. The list is intentionally fixed across workspaces, for two reasons.

First, a fixed list is what makes cross-workspace and cross-team comparisons coherent. If one team named their skill 'Frontend' and another named it 'UI Engineering,' the recommendation engine would have to do natural-language matching, which is the wrong tool for the job. A fixed vocabulary means the matching is exact.

Second, a fixed list is what makes the reinforcement loop honest. If members could invent skills on the fly, the strongest contributors would invent skills they happen to be good at, and the routing would skew toward whoever was most fluent at self-promotion. A closed vocabulary forces everyone to live inside the same map.

The nine skills are deliberately broad — broader than most teams' internal taxonomy. A frontend specialist and a design-systems specialist both declare against the same skill but at different proficiency levels, and the system uses the proficiency, plus the learned reinforcement, to distinguish them in practice.

Declared vs. learned

Every member's profile carries two strengths per skill: declared and learned.

Declared is what the member said about themselves, with one of three proficiency levels: Learning (strength 0.45), Proficient (0.65), Expert (0.85). The member sets this on their profile. The strengths are deliberately spaced so the system distinguishes meaningfully between proficiency levels, and so a single Expert declaration outweighs a default zero-knowledge prior.

Learned is what the reinforcement loop has discovered. When a member ships a task tagged with a skill, the loop bumps the learned strength on that skill — usually by a small amount, larger when the task was high-difficulty or high-impact. The learned strength is bounded so a long-tenured member does not asymptote to 1.0 on every skill they have ever touched.

The two strengths combine in the recommender as the maximum of the two — so declaring is never punished, and demonstrating is never ignored. A member who declares Learning and then ships ten tasks tagged with the skill will end up with a learned strength higher than the declared one; the recommender uses the learned number from then on.

The split also means deletions are recoverable. The trash system snapshots both declared and learned strengths when a member is deleted; restoring brings both back.

The reinforcement loop, by the numbers

The loop runs on task completion. When a task closes — open → done, exactly once, on the first transition — Kavanah's reinforcement function runs:

1. It reads the task's skill tags. If absent, it infers them from the task's description and the project's prior tags. Tasks with no inferable tags do not reinforce anything (this is on purpose; the loop will not invent skills).

2. For each tag, it identifies the actual assignees who shipped the task. Cross-checks against the workspace's active roster — if the named assignee has since been removed, no learned strength accrues to a deleted profile.

3. It increments the learned strength on each (member, skill) pair by an amount that decays with the member's prior strength on that skill (so the first ten shipments are more informative than the next hundred).

4. It marks the task as reinforced in the task_intelligence table. A reopen + reclose later cannot double-credit; only the first close counts.

This is enough machinery that, within a quarter of regular use, the learned strengths start to dominate the declared ones for tenured members. The model gets sharper without anyone having to manage it.

The per-task recommendation surface

Every task has a Skills section in its detail view that shows the agent's top three to five recommended assignees for that task, with ranked scores and reasons.

The reasons surface what the recommender used: 'declared Expert in design systems,' 'shipped 3 tasks in this skill in the last sprint,' 'current load = 1 active task,' 'overlaps with the project's Vision keywords.' Each reason is auditable; the manager can see why the recommendation looks the way it does and decide whether to follow it.

The recommendation is also accessible from the AI agent through the recommend_assignees tool — useful for ad-hoc routing decisions before a task even exists. 'Who should own a discovery sprint for the new export feature?' is a question the agent can answer using the same machinery the per-task surface uses.

The practical consequence: the manager does not have to remember everyone's skills. The system remembers, and surfaces the answer at the moment of decision.

Three failure modes to avoid

Stale declarations. Members declare skills when they join and rarely revisit. After a year, the declared profile is wrong for half the team. Build into your quarterly review: every member updates their declared skills, removing any they no longer want to be routed for. The system has a deletion path; use it.

Untagged tasks. If your team consistently ships tasks without skill tags, the reinforcement loop has nothing to credit, and the learned model never catches up to reality. The auto-tagging from the AI agent helps; make sure it is on. Tasks created by hand should get a tag at create time, even if the tag is approximate.

Name mismatches. Skills profiles are keyed by display name (matching the assigned_to field on tasks). If a member changes their display name, their existing profile points at the old name. Kavanah handles renames cleanly through the people API; manual renames in some other surface do not propagate. The fix is to use the supported rename path.