| surface_kind | canonical-sigil-source |
| runtime | codex |
| canonical_source | arcana/github-project-issue-loop/SKILL.md |
| alias_of | null |
| name | github-project-issue-loop |
| description | Use when: claiming one GitHub Project issue, refining its context, invoking define/design/plan as needed, executing through Task Session, and opening a linked PR with verification evidence. |
| argument-hint | <github-project-url-or-owner/project-number> [--repo owner/name] [--issue <number>] [--dry-run] [--limit <count>] |
| tier | arcana |
| domain | github-delivery-governance |
| version | 0.1.0 |
| origin | created from a live GitHub Project issue loop that assigned one issue, refined it, invoked artifacts, executed a task session, and opened a linked PR |
| allowed-tools | Read, Write, Glob, Grep, Task |
Sigil: GitHub Project Issue Loop
Claim one ready GitHub Project issue, convert it into governed repository execution context, run the appropriate Arcanum lifecycle path, and open a verified pull request linked back to the ticket.
Arcana: project-board intake, repository evidence synthesis, lifecycle routing, task execution, validation, PR publication, and board synchronization.
Use this sigil when:
- the user provides a GitHub Project view, project number, or issue queue;
- open issues should be assigned to the current operator before implementation;
- the ticket needs
refine to understand context, acceptance criteria, and solution shape;
invoke define/design/plan artifacts should be created based on issue risk and ambiguity;task-session should execute the bounded implementation work;- the final result should be a branch, commit, PR, issue link, verification summary, and project status update.
Expected inputs, if available:
- GitHub Project URL, project owner, and project number;
- target repository or repository filter;
- issue number, priority filter, status filter, or selection rule;
- authenticated GitHub CLI/app state;
- local checkout path and base branch;
- Arcanum skills available in the repository;
- known upstream callers, downstream consumers, generated mirrors, and dependency boundaries for the target area;
- existing regression tests, expected failing/covering tests, and validation commands;
- user assignment policy, board status policy, and PR target branch;
- validation commands and CI expectations;
- whether the run is dry-run, plan-only, or execution-authorized.
GitHub Project Issue Loop owns the delivery orchestration from project-board intake to PR creation.
- GitHub CLI/app owns external issue, project, branch, and PR operations.
refine owns discovery, seed shaping, dispatch, and handoff artifacts.invoke owns define, design, plan, and related templates.task-session owns bounded implementation execution and local validation.domainspec-subagents-strategy or another subagent strategy owns live subagent dispatch governance when research, review, or experiment subagents are required.- This sigil must not silently bypass human gates required by subagent strategies, branch protection, project policy, or destructive repo operations.
1. Resolve operating context:
- identify the GitHub Project owner/number/view;
- identify the target repository and local checkout;
- verify GitHub auth, required scopes, base branch, and clean/durable work area;
- read relevant repo instructions before mutation.
2. Intake candidate issues:
- list project items with issue content, status, priority, labels, assignees, linked PRs, and repository;
- filter out done/closed items and items that already have active linked PRs unless the user asks to continue them;
- prefer explicit issue selection; otherwise select one ready issue using priority, unassigned/assigned-to-user state, repository availability, and boundedness.
3. Claim the ticket:
- assign to the operator when allowed;
- move the project item to In Progress when allowed;
- record if either operation is blocked and decide whether execution may continue.
4. Refine the ticket:
- read the issue body, linked docs, related code, tests, and prior artifacts;
- produce or update a refinement run with issue objective, evidence index, dispatch rationale, and runtime handoff;
- keep local evidence separate from external assumptions.
5. Map the regression boundary before implementation:
- identify upstream dependencies that feed the target behavior, such as callers, routes, data contracts, configuration, generated sources, and existing tests;
- identify downstream dependents that may observe the behavior, such as UI surfaces, APIs, artifacts, docs, generated packages, CI jobs, and external consumers;
- define the intended write scope, non-goals, and affected-only hypothesis;
- create, update, or explicitly identify focused tests before the fix so the regression and adjacent behavior are observable;
- include at least one containment check, snapshot, focused assertion, or existing invariant that helps prove the fix did not spill into unrelated behavior;
- record the dependency map and test plan in refinement, invoke, or task-session artifacts before code mutation.
6. Select lifecycle depth:
- direct Task Session for low-risk, clear issues;
- Invoke Define for unclear outcome or acceptance criteria;
- Invoke Design for architecture, UX, data, integration, governance choices, or unclear upstream/downstream boundaries;
- Invoke Plan for multi-step implementation, dependency-risk sequencing, or validation sequencing;
- subagent dispatch only when the active strategy permits it and the user confirmation gate is satisfied.
7. Prepare execution:
- create or reuse an isolated branch or worktree;
- define write scope and validation surface;
- preserve unrelated local changes.
8. Execute via Task Session:
- run or document the focused regression test baseline before the fix when practical;
- implement the bounded change;
- keep artifacts, code, and tests aligned with the ticket result;
- run focused validation first, including upstream/downstream containment checks, then broader validation proportional to risk;
- compare changed files against the dependency map and explain any expansion.
9. Publish:
- commit only the intended files;
- push the branch;
- open a PR against the target base branch;
- include summary, verification, artifacts, and `Closes #` when appropriate.
10. Sync and observe:
- verify issue assignment, project status, linked PR, and CI state;
- emit telemetry using `templates/usage-telemetry.md`;
- report unresolved CI, project, or review blockers.
A meaningful execution is any run that claims or attempts to claim a project issue and produces one of: a refinement artifact, invoke artifact, task-session receipt, branch, commit, PR, validation result, or board status update.
Telemetry should capture:
- project owner/number/view;
- repository and issue number;
- selection reason;
- claim result and board status result;
- lifecycle route used;
- artifact paths created;
- upstream and downstream dependency map status;
- regression tests created, updated, reused, or blocked;
- scope containment result;
- files changed count;
- validation commands and statuses;
- PR URL;
- CI status at final poll;
- blockers and workflow gaps;
- reflection trigger state.
Use templates/usage-telemetry.md as the default JSONL schema. When repository observability is installed, append telemetry to .arcanum/observability/signals/sigil-invocations.jsonl.
Use templates/regression-boundary-map.md when a run needs a durable dependency map or when the issue touches code, UI behavior, generated artifacts, runtime configuration, data contracts, or shared tests.
Run reflection when any of these triggers occur:
- Manual trigger: the user asks to improve the issue loop.
- Usage threshold: 5 meaningful executions.
- Output threshold: 10 generated artifacts since the last reflection.
- Gap threshold: 3 related workflow gaps, such as repeated project-field ambiguity or repeated CI polling uncertainty.
- Severe gap: 1 severe workflow gap, such as claiming the wrong issue, mutating the wrong repository, opening a PR against the wrong base, losing user changes, bypassing a required gate, or reporting CI as settled when it is still running.
Reflection must produce a report using templates/reflection-report.md and must name which contract area should change before editing the sigil.
A successful execution must:
- operate on exactly one issue unless the user explicitly authorizes batch mode;
- show the issue selection reason before mutation when selection was inferred;
- assign or explicitly explain why assignment was blocked;
- keep project status and linked PR state observable;
- read local repo instructions before code mutation;
- create a branch or worktree that protects unrelated local changes;
- map upstream dependencies and downstream dependents before implementation;
- create, update, or explicitly identify focused regression tests before the fix, or record why no meaningful test can be created;
- include containment validation that proves the fix affected only the intended behavior as far as local evidence can show;
- route through
refine, invoke, and task-session according to issue risk rather than always using the same depth;
- preserve human gates required by subagent strategy or project policy;
- produce durable artifacts for non-trivial issues;
- run and report validation commands;
- open or update a PR with issue linkage and verification evidence;
- record telemetry or explain why telemetry storage was unavailable.
Avoid:
- processing several issues in one branch without explicit batch authorization;
- choosing a ticket only because it appears first on the board;
- claiming a ticket without checking repository availability and local checkout state;
- treating
gh project item-list output as stable without verifying issue state;
- skipping refine when the ticket body points to docs, audits, or acceptance criteria;
- implementing before mapping upstream/downstream dependencies and intended write scope;
- relying only on a broad full suite without a focused regression test or explicit existing-test rationale;
- widening the fix into adjacent behavior just because a nearby test is convenient;
- creating define/design/plan artifacts for trivial issues just to satisfy ritual;
- using Task Session to execute vague or unresolved work;
- opening a PR without local validation evidence;
- marking CI as passed while checks are still running;
- editing generated
.agents/skills surfaces instead of canonical sigil sources.
Return:
## GitHub Project Issue Loop Result
- Project: <owner/project-number/view-or-url>
- Repository: <owner/name>
- Issue: #<number> <title>
- Selection reason: <reason>
- Claim result: <assigned|already-assigned|blocked>
- Project status: <status|blocked|not-updated>
- Lifecycle route: <refine|invoke-define|invoke-design|invoke-plan|task-session|subagent-review>
- Dependency map: <upstream/downstream summary or artifact path>
- Regression tests: <created|updated|reused|blocked with rationale>
- Scope containment: <pass|flag|block with evidence>
- Artifacts: <paths>
- Branch/commit: <branch> / <sha>
- PR: <url|not-opened>
- Validation: <commands and status>
- CI: <summary at final poll>
- Telemetry: <written path|not written reason>
- Blockers: <none|list>
- Next step: <review|merge|wait-ci|reflect|continue-loop>
