analyzing-cybernetic-requirements

name	analyzing-cybernetic-requirements
description	Use when maintaining or resuming an existing v1 requirements.control.json run; new runs use forming-cybernetic-commitments.

Analyzing Cybernetic Requirements

Legacy v1 compatibility only. Do not create a new v1 run. New work uses $forming-cybernetic-commitments and commitment.control.json. If the target run directory does not already contain requirements.control.json, stop this compatibility path and hand off to the v2 skill.

Overview

Official persistent control facts are JSON only. Markdown is background. Detailed rules live in references/requirements-analysis-detailed-rules.md. All stage-routing gates use ../references/transition-gate-protocol.md.

Hot Path

1. If the input is pre-task intent, dissatisfaction, risk sense, method preference, symptoms, or process distrust, use $framing-cybernetic-intent.
2. Preserve the requested scope and action. Do not reduce requested behavior to a plan, readiness, framework, compatibility result, or future option.
3. Extract source_requirements before required_outcomes.
4. Always define information_sufficiency_check. If no pre-design facts are needed, set it to not_required. Facts must derive from source_requirements and/or required_outcomes, include why_needed, acceptable_evidence, current_status, evidence_ref, and be challenged by independent counterexample_review. Use schema_version: 1.3.0+. Do not use free-form required_observations.
5. Record required_result_paths before component work. Decompose into user result paths/state transitions first, then supporting components.
6. Record claim-evidence rules: each outcome states what evidence proves it; completion_logic states required outcomes and no-offset rules.
7. Information collection is part of requirements analysis. Before approval, run requirements_information_loop.py --run-dir <run-dir> --json whenever sufficiency is not satisfied/not_required; follow its next_action and rerun the gate after the action. Do not ask the user to authorize internal review or safe reads. Review planned user questions before exposing them.
8. Define counterexample_gate_contract in the requirements stage and per-outcome counterexample_gate before orchestration starts.
9. Before approval, show any missing/weak information facts as "needed before design"; do not hide them inside approved JSON or future pre-goal work.
10. Ask only questions that change approved meaning, evidence, scope, authority, or output contract.
11. Classify uncertainty as human decision, default assumption, or deferred design/planning/execution detail.
12. Produce or update requirements.control.json.
13. For controlled_run, run predict_pregoal_handoff.py; only output its handoff when it passes and What the User Approved: Approved. Do not invoke $orchestrating-cybernetic-pregoal in the same requirements-analysis turn.

Quality Gates

counterexample_gate_contract and each blocking outcome's counterexample_gate define what independent review must disprove. For schema 1.2.0+, evidence proves only its exact claim. For 1.3.0+, also challenge required result paths.

Approval Commitment

For controlled_run, show a compact commitment before approval: purpose, object, requested transformation, non-goals, done standard, result placement, evidence, sufficiency, gates, work coverage, action limits, and final format.

Required Checks

Record Meaning, Rubric, Output Contract, Design, Goal, Plan, Review, and Risk.

State Machine

Treat requirements_information_loop.py as a loop controller.

• agent_must_continue: true: execute next_action in this turn and rerun the same gate.
• RunInformationCounterexampleReview, RunInformationGathering, RepairRequirementsInformationState, and ReviseRequirements are agent-owned.
• AskUserForInformation and ReadyForUserApproval are user-owned stop points.
• ReadyForPreGoalHandoff is terminal and response-only: paste the predictor output and stop; it is not an agent-owned continuation.
• AskUserForInformation requires review of planned user questions first.
• Only user-owned actions are reported to the user as waits. Pending approval is not a stop while the next action is agent-owned.

Output Format

Before output, run the information loop when information_sufficiency_check is not complete. If the result is agent-owned, continue the loop rather than reporting a wait.

If the result is user-owned, ask only for the requested information, decision, or approval. Do not output orchestration or runtime /goal.

If requirements are approved for controlled_run, run or quote:

python3 .agents/skills/analyzing-cybernetic-requirements/scripts/predict_pregoal_handoff.py \
  --run-dir docs/cybernetics/runs/<slug>

If the predictor succeeds, paste the predictor stdout. The response must include the literal /goal line. Do not summarize it as "generated", "predicted", or "available" without printing the command. Internal runtime JSON paths are supporting artifacts; the predicted pointer is not the final approved runtime command. The pasted $orchestrating-cybernetic-pregoal command is a response-only handoff, not permission to execute orchestration in this turn.

For bounded work with only rubric check: required, route to $writing-cybernetic-goals after the rubric is confirmed; do not default to JSON pre-goal orchestration.