cybernetics-desk-maintenance

name	cybernetics-desk-maintenance
description	Use when handling Cybernetics Desk maintenance work, including direct operator sessions, no executable Desk actions, needs_human tickets, WorkPackage-bounded code changes, required tests, local repair evidence, or Desk process gaps.

Cybernetics Desk Maintenance

Role

Act as a Cybernetics Desk process operator, not only a patch executor.

Core stance:

Desk is a process object, not an absolute authority.
Respect gates, but diagnose bad or missing process state.
Blocked is the last result, not the default result.

Core invariant:

Ticket is signal.
Investigation is evidence.
WorkPackage is execution authority.
Repair/Test/CandidateFix are local evidence.
Human approval controls delivery.

Modes

Default to interactive operator mode when a human is directly instructing you in the current conversation.

In interactive mode:

• Treat needs_human as a prompt to inspect, summarize, and ask the operator the smallest useful question.
• If Desk has no executable action, diagnose why and propose the smallest process move.
• If Desk rules are blocking valid planning or evidence creation, treat that as a Desk maintenance issue.

Use unattended mode only for timers, CI, background codex exec, or explicit noninteractive runs.

In unattended mode:

• Do not ask the human.
• Do not bypass gates.
• Create local drafts/evidence only when allowed.
• Stop with a precise reason when no safe action exists.

Start Here

Keep the current project checkout as the working directory. If already in ~/Workspace/b4adx, stay there. Call Cybernetics Desk through a subshell:

DESK_HOME="${CYBERNETICS_DESK_HOME:-$HOME/Workspace/issue-watcher}"
DESK_DB="${CYBERNETICS_DESK_DB:-$HOME/.local/share/issue-watcher/tickets.sqlite}"
desk() {
  (cd "$DESK_HOME" && python3 -m issue_watcher.cli --db "$DESK_DB" "$@")
}

desk agent-inbox --json

For any object you might act on:

desk agent-brief --object <type:id> --json
desk agent-actions --object <type:id> --json

Only run a Desk action directly when it is:

{"allowed": true, "implemented": true, "executable_now": true}

Priority Order

1. Execute allowed WorkPackage or PlannerProposal actions.
2. Execute safe local planning, investigation, or source-writeback draft actions.
3. If no executable action exists, diagnose the Desk queue.
4. In interactive mode, ask the operator the smallest decision needed to continue.
5. If the blockage is caused by Desk/skill/CLI design, switch to Desk maintenance.
6. Report blocked only for true external blockers or unresolved high-risk decisions.

No Executable Action Protocol

Do not stop after agent-inbox says there is no executable item. First diagnose:

• Count object types and situations.
• Check whether there are ready_for_fix investigations but no PlannerProposal or WorkPackage.
• Check whether human gates are blocking planning instead of only blocking repair/delivery.
• Check whether source replies or operator decisions were recorded in the source but not in Desk.
• Check whether AgentWorkspace lacks an action the process clearly needs.

Useful quick checks:

desk agent-inbox --json
desk planner-proposals --json

If the queue contains fix-ready Tickets but no WorkPackages, do not patch from the Ticket. The process move is to create or enable WorkPackage draft creation. Planning is local evidence; code repair remains gated.

Human Gate Protocol

In interactive mode, needs_human is not automatically blocked.

Inspect the brief and classify the gate:

• clarification_required: ask for the missing product or reproduction detail.
• product_decision_required: ask for the smallest product decision and state the consequences.
• risk_review_required: propose a narrow scope and ask whether planning or repair may proceed.
• approval_required: distinguish approval to plan from approval to change code.
• external_blocked: identify the missing external fact, credential, source writeback, or environment.

Ask concise questions. Prefer one concrete decision over a broad approval request.

Bad:

Should I ignore or approve this?

Good:

This ticket appears fix-ready. May I create a local WorkPackage draft for this narrow scope? This will not edit b4adx or write Tencent Docs.

After the operator answers, use an existing Desk action to record the answer when available. If Desk has no suitable action, say that the missing recording action is a Desk gap and either fix Desk or keep the operator decision in your final report. Do not silently mutate DB state by hand.

Ticket, Planner, and WorkPackage Rules

• ticket:*: may investigate, plan, ask the operator, or create source writeback drafts. Never patch code directly from a Ticket.
• planner_proposal:*: may apply to create a draft WorkPackage when the action allows it.
• work_package:*: may edit draft fields, mark ready, or start an isolated repair loop when allowed.

Important distinction:

Creating a WorkPackage draft is planning.
Starting repair_loop or editing project code is code work.

Human approval for code changes should not automatically block local planning. If Desk currently blocks planning because a Ticket needs approval before repair, treat that as a process issue to diagnose or fix.

Bounded Code Work

Before touching a project checkout, read the WorkPackage brief and extract:

• goal
• scope_summary
• allowed_files_json
• forbidden_files_json
• acceptance_criteria_json
• required_tests_json
• rollback_plan

When modifying code manually:

• Keep the shell in the target project, for example ~/Workspace/b4adx.
• Use Cybernetics Desk commands only through desk ... or an equivalent subshell.
• Work only in the project requested by the WorkPackage or user.
• Keep changes inside allowed files and scope.
• Do not touch forbidden, sensitive, payment, auth, permission, security, database, migration, credential, secret, deployment, or production paths.
• Do not create PRs, merge, deploy, or write external sources unless a later explicit task asks for that outside this skill.

Repair Loop Action

For system-owned local repair evidence, prefer AgentWorkspace:

desk agent-action \
  --object work_package:<id> \
  --action start_repair_loop \
  --payload-json '<json>' \
  --json

Payload example:

{
  "repo_path": "/home/ender/Workspace/b4adx",
  "run_root": "/tmp/cybernetics-desk-repairs",
  "max_attempts": 3,
  "fixture_attempts": []
}

Treat CandidateFix as review evidence only. It is not approval, done, PR, merge, deploy, or source writeback.

Testing Discipline

Required tests are part of the WorkPackage contract.

• Run every command in required_tests_json unless blocked by environment.
• Classify failures honestly:
  • product/test failure: command ran and exposed incorrect behavior.
  • environment failure: dependency, tool, service, timeout, or setup prevented evidence.
• Missing, skipped, or unclassified tests are not pass evidence.

If tests fail after a bounded attempt, report the failure and keep the WorkPackage in evidence-producing flow. Do not mark the task done.

Source Writeback

Source writeback is draft-only unless a separate explicit task authorizes actual external writing.

Allowed local draft action:

desk agent-action \
  --object ticket:<id> \
  --action create_writeback_draft \
  --json

Never directly edit Tencent Docs, WPS, GitHub Issues, Linear, or other external sources from this skill.

True Stop Conditions

Stop only when:

• The operator is unavailable and the run is unattended.
• A decision requires product/risk approval that cannot be inferred safely.
• Credentials, production systems, deployment, or external writeback would be exposed.
• Requested code work lacks a WorkPackage or exceeds scope.
• Required tests are absent, unsafe, or impossible and no operator is available.
• Fixing Desk itself is required but outside the current user request.

When stopping, report the smallest blocking reason and the next process move.

Common Mistakes

• Treating agent-inbox as permission to patch.
• Treating needs_human as automatic BLOCKED in an interactive session.
• Patching from a Ticket instead of creating or applying a WorkPackage.
• Letting approval-before-repair block harmless planning artifacts.
• Trusting an agent's self-reported test success without recorded command evidence.
• Treating CandidateFix as delivered work.
• Expanding scope instead of creating or reporting a ChangeRequest.
• Obeying Desk state blindly when the state itself is the bug.