goal-to-issue-graph

Files (1)

• SKILL.md

SKILL.md (first lines)

# Goal to issue graph

Work backward from the promised result, not forward from the current implementation's limitations.
A graph is useful only if completing its tasks establishes the user's goal without redefining success.

This skill owns decomposition and graph review, not implementation or automatic tracker mutation.
Use `implementation-plan` for a selected change's detailed plan.
Represent an unsettled architecture as a decision task; use [independent design deliberation](../architecture-design/references/deliberation.md) when design selection is also authorized.
For a staged new-tool project, follow `new-tool-development` rather than inventing a parallel approval process.

## 1. Recover the governing goal

Read the request, relevant decisions and authoritative project guidance before interpreting a short prompt through recent work.
Distinguish the whole objective from a current milestone, paused goal or worker assignment.
For a continuation, inspect the supporting records before treating a summary's constraints as user decisions.

Write a compact root contract:

- Required observable outcomes, including distinct correctness, coverage, usability and maintenance requirements actually supported by the request.
- The complete target population and authoritative inputs, revisions or environments.
- Allowed ways to satisfy each outcome, explicit exclusions and material unresolved decisions.

Cite the source of consequential constraints, especially compatibility, preservation and required human approval.
Do not promote an implementation guard, provisional policy or conservative assumption into a user requirement.
Ask focused questions when missing context changes the objective or permitted behavior.
Use `human-review-packets` for consequential approvals or questions that require substantial context; ask simple preferences or missing facts directly.
Continue independent investigation.
If uncertainty concerns discoverable facts rather than a user choice, assign a bounded discovery task with a concrete output and consuming task.
Do not require a full specification before a graph can describe discovery work.

## 2. Inspect the actual problem

Read the relevant producers, inputs, consumers, tests, operational guidance and existing work.
Use repository evidence to distinguish completed capability, missing implementation, missing input facts, unverified behavior and genuinely unresolved requirements.
Do not turn a determined specification rule into a human decision because its implementation is missing.
Reuse existing facilities and valid completed evidence instead of planning them again.

For goals using “all” or “every,” inspect the original population, not only the subset the current pipeline accepts.
Look for boundary cases excluded by current parsers, filters, manifests or sampling.
A reconciled exclusion report does not prove successful coverage of those items.
Record evidence paths and what each receipt actually establishes; representative successes cannot establish whole-population completion.

## 3. Make root closure explicit

Separate outcomes that can succeed independently.
For example, implementing every resolved rule does not prove every required item has a usable route, and covering items through exceptions does not prove the general rules are implemented.
Require both when the user requires both.

Define what successful completion means for each required item or workflow through the real consumer.
Keep allowed evidence modes distinct: a permitted manual exception need not meet an automated derivation's proof obligations, but it must still produce the promised result.
Do not invent fallback permission or require one mechanism universally when the goal permits alternatives.
A held, skipped, missing-input or unverified state may complete diagnosis; it cannot count as a successful item unless diagnosis is itself the requested outcome.

Keep the governing root contract stable as discovery changes the work.
Preserve governing requirements, not every acceptance condition introduced by an earlier plan.
When an approach changes, remove or supersede obsolete intermediate milestones and dependencies while retaining required semantic acceptance.
Check that the replacement can achieve the root outcome without first completing the abandoned approach.
Record cancelled, duplicate, superseded and administrative closes as non-completion, with a reason and successor where applicable.
Update consuming dependencies; a closed-but-unmet prerequisite cannot count as successful completion.
Finishing the initial task list is not permission to shrink the population or weaken required acceptance.
Separate completion of the planning request from completion of the planned product.

## 4. Draft bounded outcome tickets

Choose the smallest useful deliverables with observable acceptance, not one ticket per file, implementation layer or failure message.
Group failures under a shared invariant when one general correction addresses them.
Leave low-risk mechanics to implementation; do not manufacture interfaces or exact file edits for unsettled designs.
For implementation goals, define bounded cross-component outcomes that establish and extend a working end-to-end path.
Do not merely reorder whole-subsystem tickets that still defer integration until every component is complete.

When an early decision can materially change decomposition, distinguish ready assignments from provisional downstream work.
Fully specify the decision and architecture-independent outcomes first; revise affected downstream tickets after the choice.
A complete requirements inventory does not make the implementation breakdown execution-ready.
Require only the audit outputs needed by the bounded decision, not an exhaustive current-implementation audit by default.
Tracking parents and unresolved decision or decomposition work are not ready implementation assignments.
Name the first concrete action before marking a ticket ready.
If measurement or reproduction is needed for a decision, make that evidence gathering an actionable child rather than marking the decision parent ready.
After splitting, check each child's claims, prerequisites and first action against current code and inputs; a new child can inherit stale parent assumptions.

Each ticket needs enough detail for another agent to act without reconstructing hidden decisions:

- A stable local key, concrete title and useful result tied to the root contract.
- Bounded work, owning subsystem or principal files, and relevant authority/current evidence.
- Acceptance cases and the actual consumer or check that will establish success, including necessary negatives.
- Required facts, fixtures or component outputs, their producer/owner and completion dependencies.
- Material exclusions and uncertainty that affect the work.

### Acceptance and completion evidence

Give acceptance criteria stable identifiers such as `[A1]` and `[A2]`.
Keep an identifier when its meaning stays the same; assign a new one for a material change and never reuse retired identifiers.
Map each criterion to its proving boundary and evidence class, such as a CLI fixture, property test, benchmark, API result or artifact inspection.
State applicable contexts when different input origins or execution paths could change the result.

Require an acceptance-evidence mapping for every current criterion, using the existing ticket's acceptance/evidence fields when they can express it clearly.
For each criterion, identify its current text or source reference, status and concrete supporting evidence.
Keep this mapping in one canonical record; link from handoffs and recovery state rather than maintaining parallel copies.
Use a separate completion matrix only when the existing record cannot make criterion coverage clear or an applicable governing workflow requires one.
Treat agent-authored workflow formats as revisable mechanisms, not user requirements; do not introduce stricter shared packaging merely to standardize closeout.
Identify the issue and exact integrated revision being closed, and preserve references to the criteria whose acceptance was checked.
Create additional snapshots only when existing versioned records cannot establish those identities.
Retain the revision actually tested and establish applicability to the closing revision; never present reused evidence as newly executed.
For permitted no-code-change outcomes, identify the applicable versioned inputs, products or receipts instead of inventing a fixing commit.
The issue's actual closeout owner—not merely a contributing worker—must check that every current criterion is met by applicable evidence before claiming successful completion.
A shared result may support several criteria when the mapping identifies what proves each one.
Downstream closeout records the acceptance decision and any new reconciliation, linking to existing evidence rather than reproducing its narrative.
Missing criteria, partial results, stale criterion text, unsupported worker claims and unreconciled revision mismatches block successful closure.
An investigation may complete with no change only when its acceptance permits that outcome; cancellation or supersession is not evidence that acceptance was met.

Use existing tracker validation where it checks this mapping; otherwise inspect it directly without creating another validation artifact by default.
Do not claim tool-enforced completion for checks performed only by inspection.
Do not build a new tracker or validation framework merely to write the plan.
Structural validation prevents omissions and stale-evidence mismatches; the closeout owner must still check that the evidence actually proves each criterion.
Planning defines this contract, not completed evidence or permission to execute the checks.

For risks that can invalidate an approach or prevent completion, name the observable trigger and affected outcome.
Assign an owner for the next decisive check or choice.
State what its plausible results change and when to stop the affected approach, revise the graph or obtain a user decision.
An investigation that rules out the planned route must hand off an owned next action, not leave only a blocked dependent.

From jyn514/dotfiles, Unlicense.

More from jyn514/dotfiles