SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsraise-issue

raise-issue

General & other

View repository

Updated 10-15 23:33

About this skill

Skill: raise-issue

WHAT

Purpose and context

  • Purpose: record an ISSUE with enough context into the local ledger (source of truth) + index, assign owner/dispatch, mirror it to the remote tracker if any, so another session/dev can pull it to handle via /fdk or /propose.
  • Trigger (when to use):
    • Session to ASK/design, discover a GAP or debt but do NOT do it yet — need to record enough context for another session/dev to pull it and do it.
    • "raise issue", "create issue", "open an issue for this", "log this gap to do later", "issue for another dev to pull".
    • Feature-gap, tech-debt, architecture questions, process improvement, Plan-B/optionality.
  • Non-goals: DO NOT use for: runtime bug/incident/regression currently on fire → that is orca-issue (repro-first gate). Work already ready to do immediately in the session → that is propose then code. No push (that is the job of /ship).

Boundary with other skills (read before overlapping)

  • orca-issue = INCIDENT (bug) handling loop, requires red→green reproduction. raise-issue = recording FORWARD-LOOKING work (gap/debt), no repro.
  • propose = plan to DO IMMEDIATELY in this session. raise-issue = HANDOFF, intentionally deferred, can travel to another session/machine/project.
  • raise-issue only RECORDS + ASSIGNS. No code, no editing other branches. The recipient later opens it with /fdk (if it is framework) or /propose (if it is a project feature).

Mental model

phân loại (bug → orca-issue) → query wiki (R7-f) → ledger draft (nguồn chân lý) → assign → dòng ISSUES.md → [mirror tracker theo hợp đồng issue-tracker.md] → commit ledger → xác nhận, dừng.

Input and output contract

Field Required? Meaning
In description of gap/debt + evidence yes enough for someone who did not attend the session to understand
In assignee (username) no if unclear, ask when mirroring
In contract llmwiki/wiki/sources/issue-tracker.md no if none → create from local-markdown template
Out llmwiki/wiki/sources/draft/DDMMYY-<slug>.md yes per template, with OKF frontmatter + ## Origin
Out row in llmwiki/wiki/sources/ISSUES.md yes id · title · status · assignee · tracker
Out remote issue + URL in column tracker when there is a tracker body links back to the ledger file
Out commit ledger (no push) yes the issue only exists when it travels with the repo

Rules and capabilities

  • RULE-01 (MUST): ONLY record + assign. Absolutely no code, no editing other branches/projects — the issue must travel clean.
  • RULE-02 (MUST): Context sufficient for someone-not-in-the-session: state evidence (report/council/ADR), do not assume shared memory.
  • RULE-03 (MUST): Query wiki first (R7-f) so as not to raise a duplicate of an existing issue.
  • RULE-04 (MUST): One issue per file + one index line. Do not cram multiple issues into one file.
  • RULE-05 (MUST): Do not raise status beyond open/claimed — moving to in-progress/done is the job of the receiving session.
  • RULE-06 (MUST): Touch only what the task requires — no opportunistic changes.
  • Capabilities: read wiki; write ledger + index in llmwiki/wiki/sources/; local commit; write issue to remote tracker via the adapter declared in the repo contract.

Failure boundaries

  • Is a bug/incident → cancelled in this skill, move to orca-issue.
  • Duplicate of an existing issue (query R7-f) → do not raise, report the existing issue.
  • No remote tracker/CLI → succeeded narrowly in ledger-only mode.
  • Currently on the main branch and direct commit is not allowed → commit to branch issue/<DDMMYY-slug> and state it clearly.

HOW

Main workflow

Step Type Inputs Action Outputs/exit Failure/next
W01 judgment description Classify foundation/feature-gap/tech-debt/architecture/process kind bug → stop, orca-issue
W02 deterministic kind + keywords Query wiki before writing (R7-f) link [[...]] context duplicate → stop, report the existing issue
W03 judgment context Write draft according to template ledger file —
W04 judgment draft Assign assignee + dispatch + entry, state the reason frontmatter sufficient —
W05 effect draft Add a line to ISSUES.md index no file yet → create
W06 effect tracker contract Mirror to remote tracker if available (B01) URL in column tracker none → ledger-only
W07 effect ledger + index Commit ledger (no push) commit main branch forbidden → B02
W08 deterministic result Confirm id + path + link + assignee, stop report —

Details of each step (source of truth for W01–W08):

  1. Classification issue: foundation | feature-gap | tech-debt | architecture | process. If it is a bug → stop, switch to orca-issue.
  2. Query the wiki before writing (R7-f): find related ADR/concept/draft to avoid duplication and to state the context accurately. Record the links [[...]] in the Context section.
  3. Write the draft llmwiki/wiki/sources/draft/DDMMYY-<slug>.md according to the template below — the context must be ENOUGH for someone who did not attend this session to understand immediately upon pulling it (why the issue exists, evidence, scope, done criteria).
  4. Assign: fill in assignee (responsible person/agent) + dispatch (proposed Claude/opencode/human) + entry (open with /fdk or /propose). State the reason for the choice.
  5. Register in the index: add a line to llmwiki/wiki/sources/ISSUES.md (create the file if it does not exist, header # Issues — ledger local).
  6. Mirror to the remote tracker (if any): detect host + CLI (table above); if present → create the remote issue (body links back to the ledger file), write the URL into column tracker. If not present → skip, ledger-only. Ask the assignee (username) if not yet clear.
  7. Commit ledger (GH#99): git add llmwiki/wiki/sources/draft/<DDMMYY-slug>.md llmwiki/wiki/sources/ISSUES.md && git commit -m "issue: <DDMMYY-slug> — <tiêu đề>". The ledger is the source of truth only when it travels with the repo — an untracked file means people who pull will not see it, git log --all is empty, meaning the issue does not yet exist. Do not push at this step (that is the job of /ship); if currently on the main branch and direct commits are not allowed → create branch issue/<DDMMYY-slug> then commit to it and state clearly.
  8. Confirm, DO NOT execute: report back the issue id + ledger path + tracker link + assignee. Stop here — execution is the receiving session's job.

Branches

ID Kind Guard Behavior Skip / failure Rejoin
B01 capability_optional git remote get-url origin + tracker CLI available (per contract) create the remote issue, body links back to the ledger, write the URL into column tracker not present → ledger-only; assignee not yet clear → ask W07
B02 conditional_required currently on the main branch and direct commits are not allowed create branch issue/<DDMMYY-slug>, commit to it, state clearly — W08
B03 conditional_required does not yet have llmwiki/wiki/sources/issue-tracker.md create from the local-markdown template; if there is a GitHub remote → propose mirroring gh — W06

Validation and stopping

The wiki hook checks R9 (frontmatter OKF), R2 (## Origin), R5 (valid folder) when writing; the ledger is present in git log after W07. Stop at W08 — do not execute the issue.

Examples

  • Positive: "raise issue: no cache for skill-search yet" → kind tech-debt, query not duplicated → llmwiki/wiki/sources/draft/190926-skill-search-cache.md + ISSUES.md line + gh issue create (body link ledger) → commit issue: 190926-skill-search-cache — … → report id + link, stop.
  • Boundary/failure: "create issue: approve is hung on prod" → classify as a burning bug → stop, switch to orca-issue (repro-first), do not write ledger.

Reference — Where to store — local ledger is the SOURCE OF TRUTH, remote tracker is a mirror

  • Issue = a draft file: llmwiki/wiki/sources/draft/DDMMYY-<slug>.md (same place as propose, travels with the repo when cloned — travel-able, not dependent on an external tracker). This is always the source of truth.
  • Central index: llmwiki/wiki/sources/ISSUES.md — one line/issue (id · title · status · assignee · tracker), like MEMORY.md. (Store in sources/ and NOT in wiki/ root — R5 folder-structure blocks root.)
  • Mirror to remote tracker IF ANY (to show in the Issues tab, assign real people, have notifications): auto-detect via git remote get-url origin + available CLI, mirror then write the link into column tracker. The ledger is still the source of truth; the tracker is just a copy for coordination.

Reference — Tracker — read the repo's CONTRACT, do not hardcode CLI here

How to publish/fetch/label/close/claim in this repo lives in a per-repo contract file — llmwiki/wiki/sources/issue-tracker.md (adapter boundary). This skill only states intent; the contract states how to do it. Changing tracker (adding Jira, switching GitLab) means editing that contract, NOT editing this skill. See [[issue-tracker]].

  • No contract file yet → create from template (default local-markdown: ledger is the root, no network needed); if remote GitHub exists → propose adding mirror gh.
  • Remote issue Body MUST link back to the ledger file (source of truth). Write the URL into column tracker.
  • 5 standard labels (column labels, default needs-triage): needs-triage · needs-info · ready-for-agent · ready-for-human · wontfix. Only ready-for-agent can be dispatched to headless CLI; ready-for-human is human work.

Reference — Hook wiki will bite — satisfy from the start (avoid 3 re-enables)

Every file in llmwiki/wiki/ must have: (R9) OKF YAML frontmatter at the top (type/title/status/tags/timestamp/id) · (R2) section ## Origin provenance · (R5) located in a valid folder (sources/draft/ for issue, sources/ for index). The template below already includes all three.

Reference — Issue template (frontmatter + body)

---
type: issue
kind: foundation | feature-gap | tech-debt | architecture | process
title: "<một câu>"
status: open            # open | claimed | in-progress | done | wontfix
assignee: <tên/agent>   # ai chịu trách nhiệm
dispatch: <Claude | opencode:<model> | human>
entry: /fdk | /propose  # người nhận mở bằng skill nào
priority: P1 | P2 | P3
tags: [issue, <...>]    # R9 OKF
timestamp: <YYYY-MM-DD>
id: <DDMMYY-slug>
source_session: <mô tả ngắn phiên phát hiện>
---

# Issue: <tiêu đề>

## Vấn đề (một câu)
## Bối cảnh & bằng chứng   (vì sao issue tồn tại; link [[ADR]]/[[concept]]/report/council)
## Phạm vi                 (đụng file/module/dự án nào; universal hay local)
## Không thuộc phạm vi     (chống scope-creep)
## Hướng gợi ý (không bắt buộc)
## Tiêu chí HOÀN THÀNH     (kiểm chứng được)
## Assign & lý do
## Origin                  (R2 — raise bởi ai/phiên nào, nguồn bằng chứng)