advance-technologies-foundation/clio/clio-issue-workflow

Clio Issue Workflow

Keep the workflow visible in GitHub and small enough to explain as:

claim -> investigate -> repair and verify

Treat the issue number or URL as required input. The original Clio issue remains the coordination point even when another repository owns the defect.

Route the request

• For take, triage, fix, implement, or resolve, start with the claim-clio-issue skill; claiming always precedes investigation.
• Continue with the investigate-clio-issue skill to prove the failure boundary, identify every affected repository, and check related open, unclaimed issues before deciding whether one PR should resolve multiple reports.
• Use the repair-clio-issue skill only when the user authorized implementation. A triage-only request stops after publishing the diagnosis and any authorized downstream issue relationships.
• For brainstorming, planning, explanation, or review-only requests, stay read-only and do not claim the issue.

Do not duplicate the phase procedures here. Use the phase skills as the source of truth.

GitHub visibility model

Use GitHub's existing primitives only:

• Assignee: who coordinates the issue.
• Issue Type and labels: the evidence-backed classification, normalized before investigation hands work to repair or another owner.
• Mitigation stage issue field: Investigating, Fixing, QA, or Waiting for human approval.
• Development: the linked branch and later the draft pull request.
• Relationships: create and verify GitHub-native blocked by / blocking links for confirmed dependencies, in the same repository or across repositories. Follow the investigation skill's native relationship procedure before handoff; a diagnosis comment, Markdown link, or shared PR alone does not populate the Relationships section.

Do not introduce claim records, leases, receipts, lock files, custom refs, or a separate state store.

Missing Issue Type or labels do not block intake or claim. The investigate-clio-issue skill must set and verify exactly one relevant enabled Issue Type and at least one relevant existing repository label after diagnosis. Do not invent a type, create a label, or use a placeholder classification merely to satisfy the gate.

The original issue's Mitigation stage is authoritative for the overall workflow. A closed issue needs no Done field value.

Canonical stage field

Mitigation stage is a pre-provisioned native organization-level GitHub issue field, not a GitHub Projects field. Issue-handling agents must never create, delete, or reconfigure this organization field.

The provisioning contract is:

• Organization: Advance-Technologies-Foundation.
• Name: Mitigation stage.
• Type: single_select.
• Visibility: all (Public).
• Required option names, regardless of order: Investigating, Fixing, QA, Waiting for human approval.
• Pinned issue types: Bug and Task.

Display order and pinning are administrator-facing presentation settings, not runtime readiness gates. The recommended display order is Investigating, Fixing, QA, Waiting for human approval. GitHub options carry a priority for display ordering; their position in the REST response array does not establish that order. Pinning is not returned by the issue-field REST list response.

Before the first GitHub write in every workflow, perform one read-only readiness check. Stop without assigning, branching, or commenting unless the field exists with the required type, visibility, and all four exact option names. Check option names by membership, not by array position or priority. A different response order or display order must not block claiming an issue. Report the mismatched property; do not try to repair organization settings.

Read and update it through GitHub's issue-field REST API:

1. Send X-GitHub-Api-Version: 2026-03-10 on every issue-field request.
2. GET /orgs/Advance-Technologies-Foundation/issue-fields; select the exact field name and perform the readiness check above. Resolve the field id dynamically; do not hardcode it.
3. POST /repos/OWNER/REPO/issues/NUMBER/issue-field-values with only {"issue_field_values":[{"field_id":FIELD_ID,"value":"STAGE"}]}. Do not use PUT, which replaces all issue-field values.
4. GET /repos/OWNER/REPO/issues/NUMBER/issue-field-values and verify the stored value.

If the field, option, permission, or API support is missing, report the exact failure. Do not silently substitute a label or a Projects field, and do not claim the stage changed when verification failed.

Completion

Report the original issue, assignee, current stage, linked branch or PR, owning repositories, blocking downstream issues, related-issue search and grouping decision, validation state, and any genuine human decision still required.

Do not add coordination artifacts beyond the assignee, Issue Type, labels, stage field, Development link, issue relationships, and normal issue or PR comments required to explain a blocker.