pk-team-rebalance
Command: pk-team-rebalance
SKILL.md.agents/skills/pk-team-rebalance/SKILL.md
GitHubCommand: pk-team-rebalance
Apply a pk-team-review recommendation. Targeted re-tiering of one or
more roles without full team recreation. Requires --confirm to
prevent accidental writes.
Syntax
pk-team-rebalance
--roles <list|"all"> # comma-separated role names, or "all"
--confirm # required; prevents accidental writes
--reason <string> # recorded in the DecisionRecord amendment
[--landscape-artifact <ART-id>] # explicit landscape override
[--landscape <artifact-id>] # alias for --landscape-artifact
[--weight-overrides <json>] # override stored weights for this run
[--threshold-overrides <json>] # override stored thresholds for this run
Process (sequential)
Step 1 — Load governing DecisionRecord + DEC-*-TeamWeights check
decision-record.get_decision(<governing-DEC-id>)
Read spec.inputs_snapshot to retrieve:
- Stored formula weights (used unless
--weight-overridessupplied) governance_floorparallelism_cap- The landscape artifact ID from the prior run
DEC-*-TeamWeights newer-than-governing-DEC check:
Query the decision index for the most-recent accepted DecisionRecord
tagged team-weights-override (see
references/team-weights-decision-schema.md). If one exists and its
metadata.created is newer than the governing team
DecisionRecord's metadata.created, emit this warning and do NOT
silently apply the new weights:
WARNING: A newer DEC-*-TeamWeights record (created <ISO-date>)
post-dates the governing team DecisionRecord (created <ISO-date>).
Weight policy has changed since the last pk-team-create run. This
targeted rebalance uses stored weights from the governing DEC.
To apply the updated weights across all roles, run:
pk-team-rebalance --roles all --confirm --reason "<reason>"
CLI --weight-overrides and --threshold-overrides always override
stored values regardless of DEC age.
If --roles all is specified, re-run the full pk-team-create logic
(steps 1–8 of pk-team-create) and write a new DecisionRecord instead
of amending. The remainder of this document covers the non-all
path.
Step 2 — Resolve landscape snapshot
Same resolution logic as pk-team-create Step 1. If --landscape is
not supplied, use the latest landscape-summary artifact. Warn if
older than 90 days; do not block.
Step 3 — Resolve archetype names → catalog (role, seniority) and re-score
--roles accepts archetype names (developer, senior-architect,
...). Resolve each name through the archetype-catalog mapping
(assets/archetype-catalog-mapping.yaml, layered with
context/team/archetype-catalog-mapping.yaml if present) into the
catalog (ROLE-id, seniority) pair. Operate on the matching
RoleSlot(s) in the active chartering Scope.
For each archetype in --roles:
- Look up
(role, seniority)via the mapping. Abort if the archetype is not present and no project override defines it. - Query accessible models scoped to that archetype's pinned tier:
model-recommender.query_models( G_floor=<governance_floor>, apply_user_filter=true ) - Apply the tiering formula with stored (or override) weights.
- Select the best-scoring candidate for the tier.
- If the best candidate is the same model currently filling the archetype's RoleSlot(s): report "no change needed"; skip writes.
Step 4 — End old role-slot-fill Bindings
For each archetype where a model change is needed, list the
matching RoleSlots in the active chartering Scope via
team-manager.list_role_slots(scope=<chartering-scope>, role=<ROLE-id>, state="filled"), then for each filled slot end its current fill
Binding:
binding-management.end_binding(
id=<current-role-slot-fill-BIND-id>,
reason="superseded by pk-team-rebalance: <--reason> (<ISO-timestamp>)"
)
Step 5 — Re-fill the existing RoleSlots
A targeted rebalance does NOT close-and-reopen the slot — capacity (slot count) hasn't changed; only the TeamMember and the model underneath it have. For each affected RoleSlot:
team-manager.fill_role_slot(
id=<SLOT-id>,
team_member_slug=<new-team-member-slug>,
rationale="rebalanced <ISO-timestamp>: <--reason> "
"(model: <new-model-id>, score: <score>)",
valid_from=<today>,
valid_until=<chartering Scope's ends_at, if any>
)
(If the new TeamMember does not yet exist in context/team-members/,
provision it first via the team-member skill. Ephemeral
(role, seniority) dispatches that have no persistent TeamMember
re-attach to the slot's default_model_profile instead — no fill
write is needed.)
Step 6 — (folded into step 5)
v1 split this into "create new role-assignment Binding"; v2's
fill_role_slot writes the role-slot-fill Binding inline, so a
separate step is no longer required.
Step 7 — Update roster.md in-place
Rewrite the affected rows in context/team/roster.md's routing table.
Update the "Last rebalanced" timestamp and append the reason to the
history section.
Step 8 — Amend governing DecisionRecord
Append to the governing DecisionRecord's progress_notes:
Rebalanced on <ISO-timestamp> by <actor>:
Roles changed: <list>
Reason: <--reason>
New assignments: <role> → <model-id> (score: <score>)
Weights used: C=<C> K=<K> L=<L> G=<G>
Landscape: <artifact-id> (<date>)
A new DecisionRecord is NOT written unless --roles all is used.
The --roles all shortcut
pk-team-rebalance --roles all --confirm --reason "<reason>" is
equivalent to running pk-team-create with the stored weights and
subscription, except:
- A new DecisionRecord IS written (superseding the current one).
- The deactivation sequence from
pk-team-createStep 5 applies in full.
Use this when the landscape has shifted so broadly that targeted rebalancing would touch every role anyway.
State side-effects
Ends N old role-slot-fill Bindings. Re-fills the affected RoleSlots
(no slot create/close — capacity is unchanged) and writes N new
role-slot-fill Bindings via team-manager.fill_role_slot. Amends
roster.md in-place. Appends to the governing DecisionRecord's
progress_notes. Does NOT write a new DecisionRecord (unless
--roles all).
Safety
--confirmis always required. The command prints the plan and exits if--confirmis absent.- Dry-run preview is printed before writing, even with
--confirm: show the plan and ask for explicit "proceed" confirmation in interactive mode; in non-interactive mode proceed immediately after showing the plan.