okstra 0.20.0 → 0.21.0

package/runtime/skills/okstra-brief/SKILL.md

@@ -0,0 +1,523 @@
+---
+name: okstra-brief
+description: Use when the user wants to generate a task brief file for okstra from a requirements document, an existing markdown file, an issue-tracker ticket (Linear / Jira / GitHub / Notion), a link URL, conversation context, or short user input. Produces the markdown brief consumed by `okstra-run` Step 5 (task-brief). Trigger words include "okstra brief", "make a brief", "brief 생성", "요구사항 brief 만들어", "okstra 입력 만들어", "task brief 작성", "이 티켓으로 brief", "이 링크로 brief".
+---
+
+# okstra-brief
+
+Generate a single `task brief` markdown file under the okstra project domain
+(`.project-docs/okstra/briefs/<task-group>/<task-id>.md`) so it can be fed to
+[`okstra-run`](../okstra-run/SKILL.md) as `--task-brief`.
+
+This skill produces **only the brief** — a structured "request slip". It does
+NOT write a PRD, decompose work into vertical slices, or decide modules.
+Those belong to later okstra phases (`requirements-discovery`,
+`implementation-planning`) which use cross-verification and would conflict
+with anything decided here.
+
+## Intended chain
+
+```
+okstra-brief
+  → okstra-run (requirements-discovery | error-analysis)
+    → okstra-run (implementation-planning)
+      → okstra-run (implementation)
+        → okstra-run (final-verification)
+          → okstra-run (release-handoff)
+```
+
+## When to use
+
+- The user pastes / points at a requirements doc, support ticket, bug report,
+  or rough description and wants to start the okstra pipeline.
+- The user asks to "make a brief", "okstra 입력 만들어", "brief 생성", etc.
+- A previous okstra task produced findings the user wants to convert into a
+  new follow-up task's brief.
+
+## When NOT to use
+
+- The user already has a brief file at a known path → skip to `okstra-run`.
+- The user wants to write a full PRD with user stories and implementation
+  decisions → that's `to-prd`, not this. okstra phases will generate the
+  equivalent artifacts with cross-verification.
+- The user wants to split work into issues → that's `to-issues`, and within
+  okstra it's the job of `implementation-planning`.
+
+## Authority files
+
+- `<PROJECT_ROOT>/.project-docs/okstra/project.json` — must exist; if not,
+  ask the user to run `okstra-setup` first.
+- `<PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/<ticket-id>-<file-title>.md`
+  (single / parent) or
+  `<PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md`
+  (tracker child ticket; at depth N, `sub/` is nested N times) — output
+  location for this skill. `<ticket-id>` is the raw issue-id when the source
+  is a tracker, otherwise free-text supplied by the user. `<file-title>` is
+  auto-slugified from the tracker title, otherwise from user input. Never
+  write outside this tree. Never use `.scratch/` (that belongs to `to-prd` /
+  `to-issues`).
+
+## Step 0: Resolve project root
+
+Reuse the same disk-only resolution rule as `okstra-run`:
+
+```bash
+if command -v okstra >/dev/null 2>&1; then
+  OKSTRA_CMD="okstra"
+else
+  OKSTRA_CMD="npx -y okstra@latest"
+fi
+$OKSTRA_CMD check-project --cwd "$(pwd)"
+```
+
+- `ok: true` → use `projectRoot`.
+- `ok: false` → `AskUserQuestion` (free text) for an absolute project root, then
+  re-run `okstra check-project --cwd <input>`. If still not ok, tell the user
+  to run `okstra-setup` and stop.
+
+## Step 1: Choose input source
+
+`AskUserQuestion` (tool constraint: max 4 options):
+
+- **Label**: "Source of this brief?"
+- **Options** (single-select):
+  1. `File` — path to an existing markdown / txt / issue-export file
+  2. `Issue tracker ticket` — Linear / Jira / GitHub Issue / Notion key or URL
+  3. `Link URL` — general web page, blog, spec doc, design doc, etc.
+  4. `User input` — synthesize from the current conversation context, or
+     accept a short free-text from the user
+     (default: conversation synthesis. If context is thin, fall back to a
+     single free-text question.)
+
+If the user wants to bundle multiple sources into one brief (e.g. "this
+Linear ticket + this PR link"), repeat this step to collect them. Preserve
+each source's raw content **separately** under the `Source Material
+(verbatim)` section in Step 5.
+
+### 1a. `File`
+
+Take an absolute or project-relative path via free-text. Read the entire
+file. Re-ask if it doesn't exist. Captured content is preserved **verbatim**
+in Source Material.
+
+### 1b. `Issue tracker ticket`
+
+Order of operations:
+
+1. `AskUserQuestion` (free text):
+   `"Ticket key or URL (e.g. LIN-1234, PROJ-42, https://linear.app/..., https://your.atlassian.net/browse/...)"` →
+   `ticket_ref`.
+2. Auto-detect the tracker by URL host or key prefix (`linear.app` → Linear,
+   `atlassian.net` or `JIRA_*` pattern → Jira, `github.com/.../issues/` →
+   GitHub, `notion.so` → Notion). If detection fails, ask once more via
+   `AskUserQuestion`.
+3. Check whether the tracker's **MCP tools** are loaded in the current
+   session and prefer them when available:
+   - Linear → `mcp__linear__*` family (e.g. `get_issue` /
+     `getIssueByIdentifier`). If absent, try `ToolSearch` with the keyword
+     `linear` — it auto-waits for connecting MCP servers.
+   - Jira → `mcp__jira__*` (or `mcp__atlassian__*`). Same `ToolSearch`
+     fallback.
+   - GitHub → `gh issue view <num> --repo <owner>/<repo> --json title,body,comments,labels,state`
+     (an authenticated `gh` CLI is the default path — usable even when MCP
+     is present). If `gh` is missing or unauthenticated, try `ToolSearch`
+     for `mcp__github` family; otherwise fall through to step 4 (paste /
+     skip).
+   - Notion → `mcp__notion__API-retrieve-a-page` /
+     `API-get-block-children`.
+4. If **no** MCP or CLI path is available:
+   - Ask the user via `AskUserQuestion`:
+     `"<tracker> MCP is not connected. (a) Paste the ticket body here  /  (b) Skip this source"`.
+   - Never invent ticket content.
+5. Preserve the retrieved fields (summary/title, description body, comments,
+   status, labels, assignee, linked issues) **verbatim** in Source Material.
+   When format conversion is required (e.g. Jira ADF → MD), **do not
+   paraphrase semantics** — format-only conversion is allowed. Note the
+   conversion on one line (`format: Jira ADF → Markdown (semantics
+   preserved)`).
+
+6. **Sub-ticket / child-issue / sub-task handling — recursive**:
+   - Look at child references in the fetched ticket response:
+     - Linear: `children` / `subIssues` field
+     - Jira: `subtasks` (or `issuelinks` with the `is parent of` relation)
+     - GitHub: task-list checkbox `#NNN` references + `tracked_issues`
+       (when present)
+     - Notion: child pages / sub-pages
+   - If there is **one or more** child, ask **once at the top parent**:
+     - `AskUserQuestion` (single-select)
+       - **Label**: `"This ticket has sub-tickets. How should the child tree be handled?"`
+       - **Options**:
+         1. `Generate the full tree recursively (recommended)` — walk
+            children, grandchildren, … via BFS/DFS and emit one brief per
+            node.
+         2. `Parent only; list children in Related Artifacts` — single
+            brief. Children are not fetched, only their keys/URLs are
+            recorded.
+         3. `Generate selected children only` — multi-select the direct
+            children; for each chosen child, apply option-1 policy
+            recursively to that branch.
+   - For options 1 / 3, **recurse into Step 1b sub-steps 3–5** for every
+     descendant. No depth limit. Maintain a visited set of
+     `<tracker>:<ticket-id>` to prevent cycles; on revisit, do not emit a
+     new brief — only add a link back to the existing brief.
+   - Each descendant's brief file at depth N is created under
+     `<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md` per
+     Step 2b.
+   - Each node's `Related Artifacts` should list:
+     - The parent brief's relative path (`../<ticket-id>-<file-title>.md`)
+     - All direct children briefs' relative paths
+       (`sub/<ticket-id>-<file-title>.md`)
+     bidirectionally. (Non-direct ancestors/descendants are tracked via the
+     frontmatter `parent-id` chain.)
+   - If there are no children, proceed with a single brief (depth 0).
+
+### 1c. `Link URL`
+
+Order of operations:
+
+1. `AskUserQuestion` (free text): `"Link URL"`.
+2. Fetch directly via `WebFetch`. If `WebFetch` is deferred, load its schema
+   first via `ToolSearch` with `select:WebFetch`.
+3. On fetch failure or auth required (login wall, intranet-only, etc.):
+   - Ask the user via `AskUserQuestion` to paste the body.
+   - Never invent URL content.
+4. Preserve the core content (title + body + quotes/examples) **verbatim**
+   in Source Material. For very large pages, respect the ~400-line per-brief
+   guideline and **excerpt key paragraphs only**, but do not modify or
+   summarize the excerpted text by a single character. Annotate the excerpt
+   with `[excerpt — full: <URL>]`.
+
+### 1d. `User input`
+
+Two sub-modes combined under one option.
+
+- **Conversation synthesis**: do not re-interview. Synthesize from the
+  current conversation (mirrors `to-prd`'s "synthesize, don't interview").
+  Label Source Material as `conversation synthesis` and quote key
+  utterances verbatim wherever possible.
+- **Inline input**: if conversation context is empty or thin, take one
+  free-text `AskUserQuestion`. The received text is preserved in Source
+  Material without changing a character.
+
+When both are used, record them as two separate sub-sources under Source
+Material.
+
+## Step 2: Identify task key & filename
+
+### 2a. Task group
+
+`AskUserQuestion` (free text):
+
+- `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`
+
+Slug rule: same as `okstra-run` Step 3 — slugify, must have at least one
+alphanumeric character.
+
+### 2b. Filename per source type
+
+Final brief path rule (fixed; one extra `sub/` per depth):
+
+```
+depth 0 (parent / single) :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
+depth 1 (child)           :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
+depth 2 (grandchild)      :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/sub/sub/<ticket-id>-<file-title>.md
+depth N                   :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md
+```
+
+`<sub/ nested N times>` is a meta-notation; the actual path concatenates
+`sub/` N times (e.g. depth 3 → `sub/sub/sub/`). Create the directories
+recursively as needed. No upper bound on tree depth. All parent-child
+relations are also tracked via the brief's `parent-id` frontmatter
+(directory layout + frontmatter both).
+
+`<ticket-id>` resolution:
+
+- **Issue-tracker sources (Step 1b)**: the **raw issue-id / ticket-id**
+  assigned by the tracker.
+  - Linear `LIN-1234` → `LIN-1234`
+  - Jira `PROJ-42` → `PROJ-42`
+  - GitHub `owner/repo#123` → `gh-<repo>-123`
+  - Notion (no canonical id) → `notion-<8-char-page-short-id>`
+- **File / URL / User-input sources**: `AskUserQuestion` (free text):
+  - `"Ticket / identifier (e.g. dev-9043, INV-1234, login-error)"` →
+    `ticket_id`
+
+`<file-title>` resolution:
+
+- **Issue-tracker sources**: auto-generated from the ticket title / summary —
+  do not ask the user.
+  1. Keep alphanumerics, spaces, Hangul; drop everything else
+  2. Replace spaces with `-`
+  3. Lowercase (Hangul untouched)
+  4. Cut to 60 chars at a word boundary (hard-cut at 60 if no boundary)
+  5. Trim leading/trailing `-`
+  - Example: Linear `LIN-1234 "Fix flaky login retry on 5xx"` →
+    `LIN-1234-fix-flaky-login-retry-on-5xx.md`
+- **Other sources**: `AskUserQuestion` (free text):
+  - `"File title (short summary, e.g. fix-login-retry, dev-9043-brief)"` →
+    `file_title`
+  - Apply rules 1–5 above. Re-ask on empty input.
+
+Validate the full `<ticket-id>-<file-title>` slug: must have at least one
+alphanumeric character after slugification. Apply Step 2c on collision.
+
+### 2c. Collision handling
+
+If a brief file already exists, `AskUserQuestion` with (`Skip if exists` /
+`Append timestamp suffix` / `Overwrite`). Default recommendation: `Skip if
+exists` — protects briefs the user has already edited.
+
+When multiple collisions occur in tracker multi-generation mode:
+
+- First echo the colliding file list to the user.
+- Ask **once** with `AskUserQuestion` for a bulk policy.
+- **Even when `Overwrite` is selected, confirm one more time for each
+  colliding file**, or warn that downgrading to `Append timestamp suffix`
+  is safer. Silent bulk overwrite is forbidden.
+
+## Step 3: Light context scan (optional but recommended)
+
+Only when the source material references project-specific terms or files:
+
+- Read `CONTEXT.md` / `docs/adr/` at repo root if present (domain vocabulary).
+- Resolve any file paths or symbols mentioned in the source so the brief uses
+  the project's domain language, not generic phrasing.
+
+Skip this step for purely external request material.
+
+## Step 4: Fill in missing fields (NO full interview)
+
+> **Verbatim-source rule**: Source Material collected in Step 1 must never
+> be paraphrased, summarized, or restructured. When supplementing missing
+> information, write only into the dedicated `Augmentation` section (see
+> Step 5); never modify Source Material by a single byte.
+
+Inspect the synthesized brief draft. For each REQUIRED section below that is
+empty or trivially thin **after** reading Source Material verbatim, ask **at
+most one** `AskUserQuestion` (free text) to fill it. Never ask about sections
+already covered by the source material.
+
+Augmentation content must always be confined to the `Augmentation` section
+or to a `> augmented:` blockquote inside the required section, so it is
+clear that the content is the skill's / user's added interpretation rather
+than the original source.
+
+### Step 4 policy under multi-brief (tracker recursion) mode
+
+When emitting a parent + N children at once, repeating the Step 4 interview
+per brief ruins the UX. In this mode:
+
+- **Run Step 4 interview only on the parent (depth 0) brief.**
+- **Skip Step 4 prompts for children (depth ≥ 1)** — fill only their Source
+  Material. If required sections are empty, leave them as `_(none)_`. The
+  safer default is to let `requirements-discovery` fill child gaps later.
+- Only when the user explicitly says "interview the children too" do we run
+  per-child Step 4.
+
+Required sections:
+
+- **Context** — background; what system/feature, who's affected, why now.
+- **Problem / Symptom** — current state. For bugs: repro + observed/expected;
+  for greenfield: gap between current and desired.
+- **Desired Outcome** — success shape, not a solution prescription.
+- **Constraints** — deadlines, compatibility, technical/operational limits.
+- **Related Artifacts** — files, URLs, issues, prior task-keys.
+- **Open Questions** — anything the user already flagged as undecided
+  (becomes raw material for `requirements-discovery`).
+
+Sections **deliberately omitted** (do NOT add them, do NOT prompt for them):
+
+- User stories
+- Module decomposition / implementation decisions
+- Testing strategy
+- Vertical-slice breakdown
+
+Those belong to later okstra phases.
+
+## Step 5: Write the brief(s)
+
+Use the same template per brief file. In tracker mode producing a parent
+plus N children, you write **N+1 files** (each carries only its own Source
+Material).
+
+Use this exact template. Leave a section's body as `_(none)_` rather than
+fabricating content. (The outer fence uses 4 backticks so it does not
+collide with the inner 3-backtick code block.)
+
+````markdown
+---
+type: brief
+brief-id: <ticket-id>-<file-title>          # equals the filename stem
+parent-id: self                              # `self` at root, otherwise parent's brief-id
+ticket-id: <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12 | "">
+source-type: <file | linear | jira | github | notion | url | user-input>
+task-group: <task-group>
+depth: 0                                     # 0=parent/single, 1=child, 2=grandchild, ...
+created: <YYYY-MM-DD>
+generator: okstra-brief
+---
+
+# Task Brief: <task_group>/<filename-without-ext>
+
+> Generated: okstra-brief · <YYYY-MM-DD>
+> Source type: <file | linear | jira | github | notion | url | user-input>
+> Tracker key (if any): <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12>
+> Parent brief (child briefs only): <relative path>
+> Recommended next phase: <requirements-discovery | error-analysis>  ← from Step 6
+
+## Source Material (verbatim — do not modify)
+
+Paste each source separately and as-is. No paraphrasing, summarizing, or
+restructuring. Format conversion (e.g. Jira ADF → Markdown) is allowed and
+must be annotated in the header meta.
+
+### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
+
+- ref: <abs file path | LIN-1234 | https://... | "conversation synthesis">
+- fetched-via: <Read | mcp__linear__getIssue | mcp__notion__... | gh issue view | WebFetch | user-paste>
+- fetched-at: <YYYY-MM-DD HH:MM>
+- format: <as-is | "Jira ADF → Markdown (semantics preserved)" | "excerpt — full: <URL>">
+
+```
+<Paste the raw source here without changing a single character.>
+```
+
+### Source 2 — ...
+
+(Repeat as needed.)
+
+## Context
+
+<Background / scope / why now. If self-evident from Source Material, quote
+it briefly and stop. Use the blockquote below when augmentation is needed.>
+
+> augmented: <Interpretation added by the skill or user. Do NOT add any
+> extra interpretation outside this blockquote.>
+
+## Problem / Symptom
+
+<Current state. For bugs: repro / observed / expected. For greenfield: gap
+between current and desired. Same source-quote + `> augmented:` rule as
+above.>
+
+## Desired Outcome
+
+<Shape of success. Do NOT prescribe a solution — that belongs to
+implementation-planning.>
+
+## Constraints
+
+<Deadlines, compatibility, technical/operational limits. Use _(none)_ if
+none.>
+
+## Related Artifacts
+
+- <file path / URL / issue / prior task-key>
+
+## Open Questions
+
+- <Unresolved questions the user flagged. _(none)_ if none.>
+
+## Augmentation
+
+Cross-references / interpretation / context added by the user or skill that
+is not in the original source. May be empty. Keep this section visually
+separated from Source Material — never inline it inside Source Material.
+
+- _(none)_ or `- <augmentation>`
+````
+
+### Frontmatter rules
+
+- Every brief starts on line 1 with a YAML frontmatter delimited by `---`.
+- `type: brief` is a fixed value.
+- `brief-id` must match the filename stem (`<ticket-id>-<file-title>`)
+  exactly. If the file is moved/renamed, update both.
+- `parent-id`:
+  - The root (depth 0) brief uses `self` (or its own `brief-id`).
+  - Descendant briefs use the direct parent's `brief-id`.
+- `depth` must equal the number of `sub/` segments in the path (consistency
+  check point). On mismatch, the file location wins — correct the
+  frontmatter.
+- `ticket-id` is populated only for tracker sources; leave it as an empty
+  string otherwise.
+
+Echo the file path back on one line. Show the rendered brief to the user
+inline and ask:
+
+`AskUserQuestion`: `"Proceed with this brief?"` — options `Save` / `Edit`.
+On `Edit`, return to Step 4 for the section to revise.
+
+## Step 6: Recommend next okstra phase
+
+In multi-brief mode, **evaluate each brief independently** with the rules
+below (parent and child recommendations may differ).
+
+Inspect the finalized brief and recommend the next `okstra-run` task-type:
+
+| Heuristic | Recommendation |
+|---|---|
+| `Problem / Symptom` describes a repro / log / stack trace / observable error | `error-analysis` |
+| `Open Questions` is large or `Desired Outcome` is ambiguous / needs classification | `requirements-discovery` |
+| Both / ambiguous | `requirements-discovery` (safe default — the phase itself decides branching) |
+
+Write the chosen recommendation into the `Recommended next phase:` header
+line of the brief file (Step 5). Do NOT auto-spawn `okstra-run` — leave the
+trigger to the user.
+
+## Step 7: Hand off
+
+Single brief:
+
+```
+brief saved: <abs-path>
+next: /okstra-run  (recommended task-type: <…>)
+```
+
+Multi-brief (tracker parent + children) — echo all in one block. Keep the
+`sub/` prefix visible by emitting the absolute path verbatim:
+
+```
+briefs saved (N):
+  - <abs>/<task-group>/<ticket-id>-<title>.md                   (depth 0 · parent · recommended: <…>)
+  - <abs>/<task-group>/sub/<ticket-id>-<title>.md               (depth 1 · child  · recommended: <…>)
+  - <abs>/<task-group>/sub/sub/<ticket-id>-<title>.md           (depth 2 · grand  · recommended: <…>)
+next: /okstra-run            (run a separate task-key per brief — use the filename stem as task-id)
+```
+
+Then stop. Do not invoke `okstra-run` directly — the user chooses when to
+proceed, and they may want to edit the brief externally first. In the
+multi-brief case the user also decides the order in which tasks are
+started.
+
+## Output Rules
+
+- Never write outside `<PROJECT_ROOT>/.project-docs/okstra/briefs/`.
+- Never write to `.scratch/` — that path belongs to `to-prd` / `to-issues`.
+- **Verbatim source**: never paraphrase, summarize, restructure, or reorder
+  the Source Material section. Only format conversion (ADF → MD, HTML → MD)
+  is allowed, and the conversion must be annotated in the `format:` meta.
+  Augmentation / interpretation goes only into the `Augmentation` section
+  or a `> augmented:` blockquote inside the required section.
+- If the tracker MCP is not connected, do not guess — ask the user to paste
+  the body or skip the source.
+- If a URL fetch fails or hits an auth wall, do not guess — ask for a
+  paste.
+- Never fabricate content for empty sections; use `_(none)_`.
+- Echo each `AskUserQuestion` outcome on one short line.
+- Aim for ~400 lines per brief total. If the source body is longer, **do
+  not modify** it — instead excerpt key paragraphs with the
+  `[excerpt — full: <URL>]` marker and record the original location in
+  `Related Artifacts`.
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `project.json not found` | okstra not set up in this project | Tell user to run `okstra-setup`; stop. |
+| `briefs/<group>/<id>.md already exists` | duplicate task-key | Step 2c overwrite prompt. |
+| Source file not found | bad path in Step 1 | Re-ask. |
+| Linear/Jira MCP not connected | tracker MCP missing from the session | Try `ToolSearch` once → if still missing, ask the user to paste the body. Never guess. |
+| URL fetch fails or 401 / login wall | intranet, paywall, JS-rendered page | Ask the user to paste the core body. Never guess. |
+| Tracker body is in non-MD format (ADF / HTML) | Jira description, Notion blocks | Convert format only, preserve semantics. Annotate the conversion in the `format:` meta. |
+| Brief comes out skeletal after synthesis | source too thin AND user picked `User input` with little context | Switch to inline input mode and ask one or two targeted questions. |