Multica Working On Issues

Working on Multica issues

Product contracts the runtime brief does not fully encode: PR linking vs close intent, reading linked-PR state, metadata keys, status side effects, and sub-issue enqueue behavior.

For building mention links, load multica-mentioning instead — not this skill.

Every contract below is traced to source in references/working-on-issues-source-map.md.

PR linking and close intent are two distinct contracts

The GitHub webhook runs two separate scans over an incoming PR. They are not the same gate and they read different fields.

Linking scans the PR title, body, OR branch for a routable issue key (PREFIX-NUMBER, e.g. MUL-2759). Each match writes an issue ↔ PR link row. This is the link that multica issue pull-requests reads back.

MUL-2759: add built-in issue working skill        # title prefix → links
agent/matt/mul-2759-working-on-issues             # branch ref   → links

Close intent is stricter and is a separate scan over title or body only — never the branch. It fires only for a key placed immediately after a closing keyword (Closes / Fixes / Resolves, optional : then whitespace). That adjacency is what sets the link row's close-intent flag, the gate that auto-advances the issue to done when the PR merges.

Closes MUL-2759                                    # links AND records close intent
Fixes MUL-2759
Resolves MUL-2759
Fix login MUL-2759                                 # links only — keyword not adjacent

Consequence: a bare title prefix or a branch reference links the PR but does not close the issue on merge. A closing keyword immediately adjacent to the issue key records close intent; on merge, that close intent can move the linked issue to done.

Default for code-changing issue work

When an issue run changes code in a checked-out GitHub repo, the default handoff is to open or update a PR before posting the final Multica issue comment, unless the user explicitly asked for a local-only change or no PR. This is a default, not an unconditional command: if no code changed, say no PR is needed; if PR creation is blocked by auth, failing tests, or missing remote state, report that blocker instead of pretending the run is complete.

Use a routable issue key in the PR title, body, or branch so the webhook can link the PR back to the issue. If the PR should close the issue on merge, put the key immediately after a closing keyword in the title or body, for example:

MUL-2759: fix login redirect        # links only
Closes MUL-2759                     # links and records close intent

In the final issue comment, include the PR URL when a PR exists. If the task did not produce a PR because no code changed or the user asked not to create one, say that explicitly.

Reading a linked PR's real state

When a step depends on PR state, query Multica's link table — do not infer it from branch names, GitHub search, memory, or pr_url metadata (which can be stale).

multica issue pull-requests <issue-id> --output json

Returns {"pull_requests": [...]}. Each element exposes:

• number, html_url, title
• state — the PR lifecycle as a single enum, one of merged, closed,

draft, open. There is no separate draft or merged boolean in the response; the server folds them into state (merged wins, then closed, then draft, else open).

• merged_at — non-null once merged; a second confirmation of state: merged.
• mergeable_state — mirrors GitHub (clean / dirty surfaced; other values

round-trip as unknown).

• checks_conclusion — aggregated CI: passed, failed, pending, or null

when no check suite has been observed. Backed by checks_passed, checks_failed, checks_pending counts.

So "is it merged?" is state == "merged" (or merged_at != null); "is it still a draft?" is state == "draft"; CI status is checks_conclusion.

If the command returns no linked PRs after a PR was opened, the link scanner did not observe a routable issue key in the PR title/body/branch.

Metadata: high-signal keys only

Metadata is durable issue state. Reading metadata is safe. Writing a metadata key is a state mutation and should be tied to an explicit task requirement to record that state for later readers or runs.

High-signal keys (reuse these names so queries stay consistent):

• pr_url
• pr_number
• pipeline_status
• deploy_url
• external_issue_url
• waiting_on
• blocked_reason
• decision

Not metadata: logs, summaries, files touched, timestamps, attempt counts, investigation notes. Those belong in the result comment.

multica issue metadata set <issue-id> --key pr_url --value <url>
multica issue metadata delete <issue-id> --key <stale-key>

--value is JSON-parsed by default (bool/number are sniffed); pass --type string|number|bool to force a type.

Status changes have server side effects

A status change is not cosmetic — the server enqueues or skips agent work based on it. These are the contracts, not advice:

• `backlog` parks an agent-assigned issue: the assignee is set but no task

fires. Moving backlog → todo (or any non-done/non-cancelled status) enqueues the assigned agent then.

• `in_review` is an accepted issue status. Some workflows use it while a PR

is open and awaiting review; moving to it is an explicit mutation.

• `done` on a child issue posts a system comment on its parent. If a PR

carries close intent (Closes MUL-XXXX), it advances the issue to done itself on merge — you do not also need to flip it manually.

• `cancelled` stops outstanding work; treat it as a user-driven decision.

Sub-issues: todo starts work now, backlog parks it

On an agent-assigned issue, create status decides whether the assignee fires immediately. A non-backlog status (e.g. todo) enqueues the agent at create time; backlog sets the assignee without triggering.

Parallel children — all start now:

multica issue create --title "..." --parent <issue-id> --assignee <agent> --status todo

Strictly serial children — park later steps, promote one at a time:

multica issue create --title "Step 2: ..." --parent <issue-id> --assignee <agent> --status backlog
multica issue status <child-id> todo   # promote when the previous step is truly done

Creating every serial step as todo enqueues the whole chain at once.

Incorrect → correct

PR title (link the issue):

Fix login redirect                  # incorrect — no issue key, won't link
MUL-2759: fix login redirect        # correct — links the PR

Serial sub-issues (don't start the whole chain):

# incorrect — both fire immediately
multica issue create --title "Step 2" --parent <issue-id> --assignee <agent> --status todo
multica issue create --title "Step 3" --parent <issue-id> --assignee <agent> --status todo

# correct — parked, promote in turn
multica issue create --title "Step 2" --parent <issue-id> --assignee <agent> --status backlog
multica issue create --title "Step 3" --parent <issue-id> --assignee <agent> --status backlog

References

references/working-on-issues-source-map.md — accurate file:line for every contract above: the pull-requests CLI and route, the PR response field list, derivePRState, the two-path link (extractIdentifiers) vs close-intent (extractClosingIdentifiers) proof, the backlog enqueue lines, child-done notify, and the metadata CLI. Re-derive before depending on an exact line.

working-on-issues source map

Evidence layer for SKILL.md. Every contract the skill states is traced to a current file:line here. Lines were re-derived against feat/builtin-skills after the latest main merge; the prior skill cited pre-merge lines that have since moved (see the "drifted" column). Re-confirm with the verification command at the bottom before relying on an exact line.

multica issue pull-requests — read PR links from Multica

The CLI resolves the issue ref, GETs the endpoint, and (for --output json) prints the raw {"pull_requests": [...]} body. Only --output is accepted; the default table shows NUMBER STATE TITLE URL.

PR response shape

GitHubPullRequestResponse struct: server/internal/handler/github.go:51. JSON fields the agent can read off each element of pull_requests:

• number (json:"number", line 56)
• html_url (json:"html_url", line 59)
• title (json:"title", line 57)
• state (json:"state", line 58) — the folded lifecycle enum (see below)
• merged_at (json:"merged_at", line 63), closed_at (line 64)
• mergeable_state (json:"mergeable_state", line 70) — mirrors GitHub; UI only

surfaces clean/dirty, other values round-trip as unknown

• checks_conclusion (json:"checks_conclusion", line 74) — aggregated

"passed"/"failed"/"pending" or null (no observed suite)

• checks_passed / checks_failed / checks_pending (lines 78-80) — per-suite

counts; aggregateChecksConclusion (line 183) folds them into checks_conclusion

There is no standalone draft or merged boolean in the response. The PR lifecycle is encoded in the single state string by derivePRState (server/internal/handler/github.go:994):

merged   → if PullRequest.Merged
closed   → else if PullRequest.State == "closed"
draft    → else if PullRequest.Draft
open     → otherwise

derivePRState is called when the webhook upserts the row (server/internal/handler/github.go:682), so state is what the list endpoint returns. "Is it merged?" = state == "merged" (or merged_at != null); "is it a draft?" = state == "draft". Combine with checks_conclusion for CI status.

Two distinct webhook paths: link vs close-intent

Both run inside the pull_request webhook handler, gated by the workspace auto-link flag (workspaceAutoLinkPRsEnabled, github.go:1074).

Path 1 — link (title OR body OR branch)

• extractIdentifiers regex helper: server/internal/handler/github.go:1028
• driving regex identifierRe (\b([a-z][a-z0-9]{1,9})-(\d+)\b, case-insensitive):

server/internal/handler/github.go:490

• call site: server/internal/handler/github.go:727 —

extractIdentifiers(p.PullRequest.Title, p.PullRequest.Body, p.PullRequest.Head.Ref)

Every PREFIX-NUMBER mention in title, body, or branch resolves to an issue in the workspace and writes a link row (LinkIssueToPullRequest, ~github.go:762). This is what multica issue pull-requests later reads back.

Drifted from the prior skill's github.go:727 citation, which pointed at the old call-site location for the link logic.

Path 2 — close intent (title OR body only, keyword-adjacent)

• extractClosingIdentifiers regex helper: server/internal/handler/github.go:1051
• driving regex closingIdentifierRe

(\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)[:\s]+([a-z][a-z0-9]{1,9})-(\d+)\b): server/internal/handler/github.go:501

• call site: server/internal/handler/github.go:736 —

extractClosingIdentifiers(p.PullRequest.Title, p.PullRequest.Body) (no branch arg)

Only a PREFIX-NUMBER immediately after a closing keyword (Closes/Fixes/Resolves, optional : then whitespace) sets the link row's close_intent flag — the gate that auto-advances the issue to done on merge. Fix MUL-1 closes; Fix login MUL-1 does not (adjacency). Branch names are deliberately excluded (function doc, github.go:1044-1050): a branch like mul-1/fix-login links but must never declare close intent.

Drifted from the prior skill's github.go:736 citation.

Net: a bare title prefix (MUL-2759: ...) or a branch ref links only; Closes MUL-2759 links and records close intent.

Status side effects (enqueue contracts)

Creation with --status todo (or any non-backlog status) on an agent-assigned issue fires the agent immediately; --status backlog parks it with the assignee set but no trigger. Promoting backlog → todo later fires it then (update path, line 2537).

Metadata CLI

--value is JSON-parsed by default (bool/number sniff); --type forces string/number/bool.

Verification command

Re-derive any line above before depending on it:

cd server
grep -n 'pull-requests <id>'                 cmd/multica/cmd_issue.go
grep -n 'ListPullRequestsForIssue'           cmd/server/router.go internal/handler/github.go
grep -n 'func issuePullRequestRowToResponse\|type GitHubPullRequestResponse struct\|func derivePRState\|func extractIdentifiers\|func extractClosingIdentifiers\|closingIdentifierRe' internal/handler/github.go
grep -n 'extractIdentifiers(\|extractClosingIdentifiers(\|derivePRState(' internal/handler/github.go
grep -n 'prevIssue.Status == "backlog"\|func (h \*Handler) shouldEnqueueAgentTask' internal/handler/issue.go
grep -n 'func notifyParentOfChildDone'       internal/handler/issue_child_done.go