Governed run template

A governed run works best when the request is specific, bounded, and reviewable. Use this YAML format when you want TrackeyAI to help turn intent into a controlled execution plan.

You do not need to fill in every field. Start with the sections you understand, then ask TrackeyAI to help complete the missing parts.

Copy-ready YAML template

governed_run:
  title: "Short name for this run"
  objective: >
    Describe the outcome you want. Be specific about what should be true
    when the run is complete.

  context:
    project_or_system: "Name of the app, workflow, file set, or environment"
    current_state: >
      Describe what is already known, what has already been attempted,
      and what evidence exists.
    relevant_paths_or_links:
      - "Path, URL, dashboard, folder, or file reference"
    constraints:
      - "Do not change production without approval"
      - "Use sandbox or test mode unless explicitly authorized"
      - "Preserve existing user data"
    known_risks:
      - "Authentication may fail"
      - "Billing state must not be inferred from Stripe alone"
      - "Rollback must be possible"

  authority:
    allowed_actions:
      - "Read files"
      - "Inspect logs"
      - "Propose changes"
    approval_required_for:
      - "Editing production files"
      - "Deploying changes"
      - "Changing billing, identity, entitlement, or device authority"
    forbidden_actions:
      - "Delete data without approval"
      - "Expose secrets"
      - "Bypass entitlement or identity checks"

  expected_outputs:
    - "Diagnosis"
    - "Step-by-step plan"
    - "Files or settings to change"
    - "Validation commands"
    - "Rollback plan"
    - "Acceptance checklist"

  validation:
    success_conditions:
      - "The requested behavior is visible and repeatable"
      - "The public endpoint or UI returns the expected result"
      - "No unrelated behavior changed"
    evidence_to_collect:
      - "Command output"
      - "HTTP status"
      - "Hash or version"
      - "Screenshot if UI behavior matters"
    fail_closed_conditions:
      - "Missing identity"
      - "Missing entitlement"
      - "Missing device authority"
      - "Missing or invalid evidence"

  rollback:
    backup_location: "Where the pre-change backup or checkpoint is stored"
    restore_steps:
      - "Stop the changed service if needed"
      - "Restore the backed-up files or settings"
      - "Restart the service"
      - "Re-run validation"

  notes:
    - "Add anything TrackeyAI should know before guiding the run"

Minimal example

governed_run:
  title: "Add installer link to dashboard"
  objective: >
    Add the current TrackeyAI Windows installer link to the account dashboard
    and verify that users can download the correct release.

  context:
    project_or_system: "TrackeyAI website"
    current_state: >
      Installer is uploaded to the public downloads folder and returns HTTP 200.
    relevant_paths_or_links:
      - "https://trackeyai.com/downloads/TrackeyAI-Setup-1.0.0-win-x64.exe"
    constraints:
      - "Do not change billing or entitlement logic"
      - "Back up website files before editing"
      - "Restart only after a successful build"

  authority:
    allowed_actions:
      - "Read website files"
      - "Patch dashboard copy and download metadata"
      - "Build and restart the website"
    approval_required_for:
      - "Any billing, Auth0, Stripe, or entitlement change"
    forbidden_actions:
      - "Expose secrets"
      - "Delete production files without backup"

  validation:
    success_conditions:
      - "Installer URL returns 200 OK"
      - "Dashboard links to the current installer"
      - "Displayed SHA-256 matches the published installer"
    evidence_to_collect:
      - "curl -I output"
      - "SHA-256 value"
      - "Build output"

Questions to ask TrackeyAI

Use these questions when you are unsure how to structure a governed run.

Planning questions

• "What is the safest governed plan for this task?"
• "What information is missing before this run is safe to execute?"
• "What should be read-only discovery, and what would require approval?"
• "What is the smallest safe change that would satisfy this objective?"
• "What assumptions am I making that need evidence?"

Risk and authority questions

• "Which parts of this task affect identity, billing, entitlement, device authority, or production access?"
• "What actions should be forbidden for this run?"
• "What should require explicit approval before continuing?"
• "What would make this run fail closed?"
• "What rollback path should exist before any change is made?"

Prompt-building questions

• "Turn this goal into a governed-run YAML template."
• "Rewrite this request so it is specific, bounded, and testable."
• "What success conditions should I use for this run?"
• "What evidence should I collect to prove the run passed?"
• "What should the acceptance checklist be?"

Debugging questions

• "Based on this error output, what is the likely failure class?"
• "Is this a product defect, environment issue, permission issue, missing fixture, or validation gap?"
• "What should I test next without changing anything?"
• "What evidence would distinguish between these possible causes?"
• "What is the next safest command to run?"

Release and validation questions

• "What must pass before this can be considered release-ready?"
• "What public endpoint, UI route, or file hash should I validate?"
• "What regression checks should run after this change?"
• "What proof should be saved before cleanup starts?"
• "What should not be cleaned up yet?"

Better governed requests

Weak request:

Fix the dashboard.

Better request:

Inspect the dashboard download path, identify why the installer link is missing, propose the smallest patch, back up files before editing, build only after patching, restart only after a successful build, and validate the public installer URL and dashboard link.

The second request gives TrackeyAI enough structure to preserve safety, collect evidence, and avoid unrelated changes.