Develoop

View saved version →

---
name: cleanup-slops
description: Find and simplify implicit state machines across a repository or a specified pull request without regressing behavior. Use for requests such as "find all of the implicit state machines in my app" or a cleanup pass that removes redundant state and consolidates scattered transitions for readability and maintenance.
license: MIT
---

# Cleanup Slops

Start from this prompt:

> find all of the implicit state machines in my app

Use it as a discovery lens for a behavior-preserving cleanup. Find lifecycle
rules hidden across mutable flags, nullable values, effects, callbacks, and
duplicated status fields. Remove unnecessary stored state and scattered
coordination; make essential transitions easier to understand and maintain.

An implicit state machine exists when the meaning or legality of an operation
depends on prior events and combinations of state, while its transitions and
invariants are distributed across the code. Multiple booleans alone are not
evidence: independent settings may legitimately vary independently.

## Establish the boundary

- For a repository-wide request, map application entry points and runtime
  modules, then track which areas were inspected. Start with first-party code;
  exclude generated, vendored, and build output unless they own relevant
  behavior. Do not claim exhaustive discovery from a few keyword searches.
- For a specified PR, resolve the target repository, base, and head. Inspect the
  merge-base-to-head diff and the full enclosing implementations, callers,
  consumers, and tests needed to understand it. Address machines introduced,
  modified, or relied on by that implementation; record unrelated discoveries
  without expanding the patch. Keep findings tied to the inspected head.
- Honor explicit inspection-only or planning requests. When cleanup is
  requested, carry supported fixes through implementation and validation.
  Local cleanup does not itself authorize remote comments, push, merge,
  deployment, or changes to external data.
- Read repository guidance and preserve unrelated working changes. For a new
  cleanup branch, use the existing checkout unless isolation is required or
  requested. Keep an existing PR's branch context when working on that PR.

## Discover and reconstruct

Trace behavior from entry points and state owners, using searches only as
leads. Inspect loading and error flags, selected IDs plus cached objects,
status enums, mirrored props or store values, subscription and connection
lifecycles, pending promises, timers, retries, queues, persistence, and cleanup
handlers. Follow reads, writes, reset paths, and async completions across
module boundaries. Include server, worker, and client paths where present.

Keep a compact inventory for each candidate:

| Evidence | What to establish |
| --- | --- |
| Owner and locations | Who owns the state, who writes it, and who observes it |
| Effective states | Reachable combinations and combinations ruled out by code or contracts |
| Events and transitions | Entry, success, failure, cancellation, retry, reset, and disposal paths |
| Invariants and effects | What must remain true, including observable output and side effects |
| Decision | Derive or remove redundant state, consolidate essential transitions, preserve, or defer with a reason |

Distinguish demonstrated behavior from inferred intent. A suspicious combination
is a candidate until its producers, consumers, and reachable transitions are
understood. Prioritize redundant sources of truth, impossible combinations,
duplicated transition logic, and effects that synchronize state with other
state. Preserve independent axes such as cached data and an in-flight refresh.

## Establish regression evidence

Before editing a candidate, identify its observable contract and run the
relevant existing checks. Record baseline failures separately. Where coverage
does not establish that contract, add focused characterization tests at the
public behavior boundary; confirm they pass before refactoring. Test outcomes
and transitions, rather than private field names or the new representation.

Include the failure and recovery paths the candidate actually supports. For
async work, exercise overlapping requests completing out of order,
cancellation, retry, and disposal where relevant. Preserve side-effect count
and ordering, error propagation, and resource release. For UI paths, exercise
the affected interaction in the available browser or device as well as tests.

Check external consumers and persisted state before removing or renaming a
field. Preserve public APIs, serialized representations, event payloads, and
storage compatibility unless a contract change is explicitly in scope. An
internal simplification may need an adapter at that boundary.

## Simplify one candidate at a time

Choose the smallest representation that expresses the existing contract:

- Derive values from an authoritative source instead of storing and
  synchronizing equivalent flags or copied objects.
- Remove unreachable branches or obsolete transitions only after tracing
  their producers and externally supplied or restored state.
- Group states that are demonstrably mutually exclusive when that prevents
  invalid combinations. Keep independent facts independent.
- Give essential lifecycle transitions one clear owner. A local transition
  function, reducer, or discriminated union may help when the lifecycle cannot
  be eliminated; do not add a framework or universal state-machine layer by
  default.
- Keep guards that enforce timing, request ownership, idempotency, cleanup,
  or consistency. Fewer flags or lines are not sufficient evidence of a safe
  simplification.

Use [references/decision-examples.md](references/decision-examples.md) when
deciding whether state is redundant or protects meaningful history.

Keep edits reviewable and run the focused checks after each coherent change.
Do not quietly fix a pre-existing behavioral bug as part of an equivalence
refactor. Record it separately unless the requested scope includes its fix.
If a candidate's contract is ambiguous or cannot be verified, defer that
candidate with concrete missing evidence and continue with supported cleanup.

## Verify and report

Run the repository's required checks and the tests for affected consumers.
Revisit the inventory: verify that removed state has no remaining writers or
consumers and that essential transitions still have an owner. Review the diff
for unrelated churn, changed defaults, altered event ordering, and accidental
API or persistence changes.

Report the inspected scope and PR head when applicable, the machines found,
what was simplified, what was preserved or deferred and why, and the checks
actually run. Identify baseline failures and untested behavior explicitly;
do not claim regression freedom from passing unrelated checks. State any
uninspected areas when reporting repository-wide coverage. Finish when the
in-scope inventory is addressed or explicitly deferred with evidence; do not
keep rewriting adjacent code merely to reduce the machine count.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: gh-autoreview-resolve
description: Run a bounded GitHub automated-review and resolution loop for a specified pull request. Use when an agent must mark a PR ready for review, confirm the automated reviewer started through an eyes reaction, wait for a thumbs-up or concrete review response, validate and address review threads, request a narrowly focused `@codex review` follow-up when warranted, prevent review scope creep through PR comments or a gh-create-issue follow-up, and optionally merge with the user's preferred strategy.
license: MIT
---

# GitHub Auto Review Resolve

Move one specified pull request from draft through a conservative automated-review loop. Keep the PR's original implementation goal authoritative; do not turn review follow-up into an open-ended audit.

## Adapt to the agent host

Read [references/agent-harnesses.md](references/agent-harnesses.md) before
choosing GitHub, waiting, or user-interaction tools. The `@codex review`
mention in this workflow addresses GitHub's configured Codex reviewer; it does
not require the agent executing this skill to be Codex. Do not post the mention
unless the repository actually uses that reviewer.

## Establish the contract

1. Read repository instructions, the linked issue, PR body, changed files, current head, checks, and existing review threads.
2. Record the original goal, acceptance criteria, explicit non-goals, requested review focus, whether merge is authorized, and the user's preferred merge strategy.
3. Verify `gh auth status`, the repository, PR number, local checkout, and unrelated working-tree changes before mutations.
4. Run `scripts/inspect_review_state.py <PR> --repo OWNER/REPO` for one normalized, fully paginated baseline. Treat its GraphQL `reviewThreads` result as the source of truth for unresolved work. The inspector first reads `gh api rate_limit`, preserves 200 GraphQL points plus a five-point next-query buffer by default, and reports every query's `cost`, `remaining`, `used`, and `reset_at` values.
5. Use only one active observer for an `OWNER/REPO#PR`. When waiting is required, give the loop to one `--watch` process and let other agents or tasks reuse its result instead of polling independently. The watcher enforces this on the same host with an advisory process lock in a user-private directory; it refuses symlinks or non-regular lock files and releases ownership automatically on process exit. Operators must preserve the same single-observer contract across hosts.

Do not merge unless the user explicitly requested it. If merge was requested but the strategy is neither stated nor reliably discoverable, ask rather than guess.

## Start review

1. If the PR is a draft, record the UTC time and full head OID immediately before the ready transition. Retain the OID so the ready-triggered review can be tied to unchanged code even though GitHub does not attach a `Review head:` marker to that implicit request.
2. Then run `gh pr ready <PR> --repo OWNER/REPO` and inspect with `--after <ISO_TIME>` using the recorded transition time so old bot activity is not mistaken for the new review. If the PR is already ready, do not repeat the transition; reuse its recorded trigger evidence when available, and never substitute a later observation time for the ready time.
3. Confirm review start from an `eyes` reaction on the PR or the active `@codex review...` comment. If feedback or a pass response arrives before eyes is sampled, accept that as a completed start race.
4. If no start signal appears after a reasonable bounded wait, confirm there is no active request, then post exactly one `@codex review` comment. Include the current full head OID on its own `Review head:` line so a later reaction can be tied to that exact code. Never post another request while eyes is present.
5. When the user supplied a review target, request it narrowly and keep the head marker:

   ```text
   @codex review
   Review head: `<full head OID>`

   Focus on <specific contract, regression, or risk>.
   ```

Avoid leading the reviewer toward a predetermined implementation or inviting a repository-wide audit.

## Wait and classify

Use `inspect_review_state.py <PR> --repo OWNER/REPO --watch --after <ISO_TIME>` for a bounded wait. It takes one authoritative snapshot, then uses a lightweight transition fingerprint instead of repeatedly loading every thread and check. An unchanged fingerprint backs off from 60 to 120 to 240 seconds and then caps at 300 seconds, with jitter. A transition resets the backoff and triggers another fully paginated snapshot; even without a detected transition, the watcher forces an authoritative refresh every 10 minutes. Defaults cap a watcher at 20 minutes, 40 GraphQL requests, 20 pages per connection, and 90 seconds of actual GraphQL execution. Each `gh` request receives the remaining execution/deadline timeout. Adjust a ceiling only for a concrete PR-size or latency reason.

Do not run a separate shell polling loop around the inspector. Keep the user informed during longer waits while the one watcher owns observation.

- `eyes > 0`: review is still running; keep waiting.
- `thumbs_up > 0`: no-issue pass tied to the current head, unless unresolved threads still exist.
- `ignored_thumbs_up > 0`: a thumbs-up was observed without a matching explicit `Review head:` anchor. This is not automatically invalid. Accept it as the initial ready-triggered pass when the connector reaction occurred after the recorded ready time, the head recorded before ready still equals the current head, pagination is complete, and no unresolved thread exists. Otherwise do not treat it as a current-head pass. Absence of the marker alone does not require another `@codex review` comment; request an anchored review only when current-head applicability remains materially uncertain or a focused re-review is independently warranted.
- `outcome: passed`: accept either thumbs-up or an explicit connector response such as “Didn't find any major issues,” provided the response applies to the current head.
- `outcome: review_feedback`: inspect every unresolved thread.
- `outcome: review_response`: inspect the response and thread state; do not assume pass or failure.
- `outcome: not_started_or_pending`: allow short propagation time, then diagnose configuration or request state without posting duplicates.
- `outcome: pagination_incomplete` or `pagination_incomplete: true`: stop. The inspector already followed cursors until an explicit ceiling or a missing/repeated cursor prevented progress. Read `pagination.unfinished`, raise a justified ceiling if safe, and resume only after checking the reported cursor and quota.
- `outcome: rate_limited`: this is an operational pause, not review failure. The inspector reads included response headers, so honor `retry_after_seconds` for secondary limits or wait until the reported `reset_at`; do not immediately retry.
- `outcome: preflight_unavailable`: the inspector could not establish the GraphQL budget and failed closed before issuing a GraphQL query. Restore `gh api rate_limit` access before retrying.
- `outcome: budget_exhausted`: stop the observer and inspect its request, page, or execution-time ceiling before deciding whether one bounded rerun is justified.
- `observer.outcome: watch_timeout`: the review is still non-terminal. Report the current state and decide whether another bounded observation window is warranted.
- `observer.outcome: observer_active`: reuse the existing observer. Do not start another watcher for the same PR.

Check that the review applies to the current head. A stale or outdated anchor is evidence to reassess, not a reason to edit blindly. Never report `passed`, ready, or zero unresolved threads unless `pagination.complete` is `true`.

## Resolve feedback

For each unresolved thread:

1. Reproduce or disprove the claim against current code, tests, runtime behavior, and the PR's original contract.
2. Classify it as:
   - **valid and in scope**: caused by the PR or violates its acceptance criteria;
   - **valid but out of scope**: pre-existing or an adjacent enhancement not needed for the PR goal;
   - **invalid, duplicate, or stale**: contradicted by evidence, already handled, or based on an obsolete head.
3. For valid in-scope findings, make the smallest coherent fix. Preserve unrelated work, follow repository instructions, add focused regressions, and run validation proportional to risk.
4. Commit and push normally. Update the PR body when the new commit materially changes its described behavior or validation evidence.
5. Reply on the exact thread with concise evidence: validity decision, root cause, fix or rejection rationale, tests, and commit when applicable.
6. Resolve the thread only after the reply is posted. Re-fetch the current head, checks, reactions, and unresolved thread count.

Do not silently resolve a substantive thread and do not equate reviewer priority labels with proven validity.

## Bound the loop

Use one initial review and, after in-scope fixes, normally one explicit focused verification re-review. When those fixes stay within the original development scope and that pass leaves no concrete regression concern, finish the loop.

Do not treat that focused re-review as an absolute one-round cap. If a valid finding's fix changes a sensitive boundary or creates or leaves a concrete in-scope regression risk, request further focused re-review as needed. Before every additional round, require all of the following:

- the preceding review produced a valid in-scope finding and a corresponding code change, or new evidence identifies a specific regression risk in that change;
- the request names the exact current head and only the affected contract, regression, or risk;
- the work remains within the PR's original goal and does not broaden the implementation scope;
- no other review request is active.

Do not request another round merely to obtain stronger reassurance or a different reaction. After each response, reassess the evidence and stop as soon as no concrete regression concern remains. Stop or split follow-up when any of these occurs:

- new comments move beyond the PR's original goal;
- the concern is pre-existing and non-blocking for this PR;
- fixes begin spreading into unrelated modules or architectural redesign;
- the next request cannot identify a new code change or a concrete regression hypothesis caused by the preceding fix;
- the reviewer repeats an already answered behavior without new evidence;
- the acceptance criteria and required regression coverage are already satisfied.

When stopping:

1. If no separate issue is warranted, comment on the PR with the scope decision and evidence, then stop the loop.
2. If the finding is real and deserves implementation, invoke `gh-create-issue` using the current agent host's skill syntax. Research primary evidence, check for duplicates, create an implementation-ready English follow-up issue, comment its link and why it is separated, then stop this review line.
3. If an in-scope release blocker remains unresolved, do not merge. Report the blocker.
4. If only a non-blocking out-of-scope follow-up remains, the PR may proceed after the comment or issue link is recorded.

## Finish and optionally merge

Before declaring the loop complete, verify the exact final head, required checks, no active eyes request, and zero unresolved review threads. A pass response is sufficient; do not manufacture extra review rounds merely to obtain a different reaction shape.

Also verify `pagination.complete: true` and `rate_limit.status: ok`. Partial data may contain useful feedback, but it is never terminal success.

If merge was requested:

1. Reconfirm the PR is ready, mergeable, current checks are green, and no in-scope blocker remains.
2. Use the user's preferred method: `--rebase`, `--squash`, or `--merge`.
3. Merge in any user-specified dependency order. Do not delete branches or worktrees unless requested.
4. Re-fetch and report the merged state, resulting commit, linked issue state, and any follow-up issue.

If merge was not requested, stop at the verified ready-to-merge state.

## Inspection script

Run from this skill directory:

```bash
python scripts/inspect_review_state.py 123 --repo owner/repository
python scripts/inspect_review_state.py https://github.com/owner/repository/pull/123 --after 2026-07-23T00:00:00Z
python scripts/inspect_review_state.py 123 --repo owner/repository --watch --after 2026-07-23T00:00:00Z
gh api rate_limit --jq '.resources.graphql'
```

The inspector fetches top-level comments without nested reactions, identifies the latest active anchored review request, and then fetches reactions only for that comment. It follows cursors for PR reactions, comments, reviews, threads, active-request reactions, check contexts, and nested thread comments. It collects every check context twice and requires the two snapshots to match so a change outside the lightweight last-20 suffix cannot produce false completion. Missing or non-advancing cursors fail closed with the exact unfinished connection.

Use `--self-test` to validate the script's state classifier without GitHub access. Use `--reserve`, `--query-cost-buffer`, `--max-requests`, `--max-pages`, `--max-seconds`, or the watch timing flags only when the defaults do not fit a verified repository constraint.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: gh-create-issue
description: Create high-quality GitHub issues or issue drafts from repository evidence, user intent, and external documentation. Use when the user asks an agent to create, draft, file, open, or prepare an implementation issue, bug report, feature request, follow-up issue, or GitHub issue with researched facts, scope, non-goals, suggested direction, acceptance criteria, and validation notes.
license: MIT
---

# GH Create Issue

Create implementation-ready issues that preserve what was learned during investigation. Treat the issue as an engineering handoff: concrete enough for a future implementer to start safely, scoped enough to avoid accidental broad rewrites, and honest about uncertainties.

Creating issues directly requires GitHub CLI or an equivalent authenticated
GitHub integration. Without write access, produce a complete issue draft
instead of claiming that an issue was created.

## Adapt to the agent host

Read [references/agent-harnesses.md](references/agent-harnesses.md) before
choosing tools or invocation syntax. Treat named commands as one implementation
of a capability: use the current host's connected GitHub integration when it
offers the same read or write operation, and fall back to `gh` when it does not.

## Workflow

1. Inspect issue style before writing.
   - If the target repository or sibling repository has recent issues, read the newest relevant issues first.
   - Mirror the useful level of detail, section shape, and tone without copying irrelevant structure.
   - If there are no existing issues, use the default template in `references/issue-structure.md`.

2. Research from primary evidence.
   - Inspect the current code, docs, tests, workflows, logs, or issue/PR history that define the problem.
   - For platform, API, protocol, or framework behavior, verify against primary sources when facts may be stale or subtle.
   - Record discovered facts in the issue body, not just in the conversation.

3. Separate facts from direction.
   - Use concrete references for observed current behavior.
   - Mark recommendations as suggested direction, not as already proven design.
   - Include assumptions and open questions when they affect implementation choices.

4. Define boundaries.
   - State the goal.
   - State scope and non-goals explicitly.
   - Preserve user-specified constraints and exact nouns.
   - Avoid turning a narrow follow-up into a broad redesign.

5. Write acceptance criteria that can be verified.
   - Prefer observable behavior, commands, CI jobs, manual smoke tests, screenshots, logs, or API responses.
   - Include regression checks for existing behavior.
   - Include platform-specific validation when the issue depends on platform behavior.

6. Create the issue only after reviewing the body.
   - If the user asked to create the issue, use the repository's issue tool or `gh issue create`.
   - If the target repo is ambiguous, resolve it from cwd/remotes before creating.
   - If creation is risky or the user asked for a draft, return the issue body instead.

## Reference Files

- Read `references/issue-structure.md` when drafting any issue body.
- Read `references/research-and-evidence.md` when deciding what investigation to perform or how to word discovered facts.
- Read `references/checklist.md` before creating or returning the final issue.
- Read `references/agent-harnesses.md` before choosing host-specific tools or invocation syntax.

## Style Rules

- Write GitHub issue titles and bodies in English, even when the user request or source discussion is in another language.
- Translate user-provided requirements, examples, and context into clear English for the issue body.
- Preserve exact non-English product names, UI labels, field values, error text, commands, and quoted strings when those literals are the implementation target or evidence.
- Prefer concise section prose over long bullet piles, but use bullets for facts and criteria.
- Use exact code symbols, routes, file paths, command names, event names, API names, and error messages.
- Do not overpromise. If something was inferred, say it was inferred.
- Do not include private secrets, credentials, tokens, or sensitive local-only paths unless the path is necessary and safe.
- Do not file duplicate issues without checking the target repository's existing issues when practical.

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: gh-implement-issue
description: Implement GitHub issues through a complete branch-to-PR workflow. Use when the user asks an agent to implement, fix, or ship a specific GitHub issue, including reading issue comments, confirming the implementation contract, creating a branch, making atomic commits, validating, pushing, opening or updating a PR, and handling issue-linked review/CI follow-up. Use related skills or integrations when available; otherwise inspect the repository, issue, PR, CI, and review context directly with the available tools.
license: MIT
---

# GH Implement Issue

## Overview

Use this when the job is not just "make a patch", but "implement the GitHub issue and carry it to a validated PR-ready state". The output should be a branch/commit/PR state that matches the issue scope and a closeout that names validation and unresolved risk.

## Adapt to the agent host

Read [references/agent-harnesses.md](references/agent-harnesses.md) before
choosing GitHub, browser, delegation, or user-interaction tools. Use equivalent
capabilities exposed by the current host; command and tool names in this skill
are examples, not hard dependencies.

## Workflow

1. Establish context before editing.
   - Read repo `AGENTS.md` / local instructions.
   - Run `git status --short --branch` and protect unrelated dirty work.
   - Fetch the issue/PR/source-of-truth first: `gh issue view`, `gh pr view`, linked comments, upstream PRs, docs, or paired repositories.
   - If the issue touches separable surfaces and the current host plus repository instructions permit delegation, use subagents for independent discovery, such as backend contract vs frontend UI vs upstream library behavior. Otherwise perform the same discovery sequentially.

2. Confirm the implementation contract.
   - Restate the concrete behavior, non-goals, and expected output.
   - Check whether the issue number is actually an issue, PR, duplicate, stale branch, or follow-up.
   - When the target is a GitHub issue you will implement, assign yourself before branch planning or code edits: `gh issue edit <issue-number-or-url> --add-assignee "@me"` (or an equivalent GitHub API/UI action). Do not remove existing assignees. If assignment is impossible because the target is not an issue or permissions are missing, stop and report the blocker before implementation.
   - For cross-repo changes, inspect the upstream contract before patching the downstream repo.

3. Plan the branch and commit slices.
   - Create or switch to the requested feature branch before editing.
   - Keep commits aligned with real task boundaries: core behavior, UI, docs, release/version, review fix.
   - If branch scope grows beyond its name or PR text, rename or update the branch/PR instead of letting metadata drift.

4. Implement narrowly.
   - Follow local patterns and repo validation style.
   - Stage only requested files; leave unrelated worktree noise unstaged.
   - Add focused regression tests when behavior is testable.
   - For user-facing UI or runtime behavior, verify with a real browser, device, deployment, or output surface when feasible.

5. Validate in layers.
   - Run the smallest focused test first.
   - Then run the repo-expected checks for the touched surface, such as typecheck, lint, build, unit tests, dry-run deploy, or package metadata checks.
   - If a command cannot run because an environment dependency is missing, record the exact blocker and continue with the strongest available narrower proof.

6. Publish.
   - Push with upstream tracking once the local branch is coherent.
   - Create a draft PR for substantial or still-reviewing work unless the user asked otherwise.
   - Write PR titles and bodies in English. The PR body must be English even when the issue or conversation is in another language.
   - Translate the implemented issue requirements into clear English in the PR body, while preserving exact non-English UI labels, product names, error text, commands, and quoted literals when they are part of the change or evidence.
   - PR body should match the actual diff and include summary, validation, risks/known gaps, and GitHub closing keywords such as `Closes #123` when the PR fully implements the target issue.
   - Do not close the implemented target issue manually after opening the PR. Leave it open so GitHub closes it automatically when the PR with the closing keyword is merged.
   - If a related issue is duplicate or stale rather than implemented by the PR, close it manually only when the user explicitly asked for duplicate/stale issue cleanup and the evidence is verified; otherwise explain the stale/duplicate assessment in the PR body or final response.
   - Re-check CI or PR checks before claiming status in the PR body.

7. Follow up on review/CI.
   - If review-thread helper skills or GitHub integrations are available, use them to inspect unresolved review threads and preserve thread state. If they are not available, use `gh pr view`, `gh api`, or the available GitHub interface to identify unresolved review comments before patching.
   - If CI-debugging helper skills or integrations are available, use them to inspect failing GitHub Actions or external check details. If they are not available, use `gh pr checks`, `gh run view`, linked check URLs, or local reproduction commands to collect the failure evidence.
   - For valid review comments or CI failures, patch, validate, push, reply where appropriate, and re-check the unresolved thread or check status.
   - For invalid or deferred comments, explain concretely before resolving only if that matches the user's hygiene rule.

## Closeout Checklist

- Branch name and PR number.
- Target issue closure path: confirm the PR body contains the right closing keyword, or explain why the issue should remain open.
- Commits made, grouped by intent when more than one.
- Validation commands run and their result.
- Commands not run and why.
- Unrelated dirty files left untouched.
- Remaining risks or follow-up issues.

## Pitfalls

- Do not infer scope from a title alone; issue comments and paired upstream code often change the real contract.
- Do not let generated or placeholder PR bodies survive after implementation.
- Do not resolve review threads from flat PR comments alone; thread state matters.
- Do not call a feature done from tests only when the user asked for real UI, device, deployment, or artifact verification.
- Do not combine unrelated cleanup with issue work just because it is nearby.
- Do not run `gh issue close` for an issue implemented by the current PR. Use PR closing keywords and let merge close the issue.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: writing-strategy
description: Choose writing and narrative strategies from a curated bilingual strategy set, then produce a Markdown article outline or table of contents. Use when the user asks how to structure a draft, essay, article, post, proposal, column, case study, story, marketing copy, or other writing based on a topic, material, purpose, audience/readers, tone, or language. The skill selects a best-fit strategy, avoids overusing generic problem-solution frames, keeps Korean and English strategy names as canonical references, and displays strategy names in the user's output language unless bilingual names are explicitly requested.
license: CC-BY-NC-SA-4.0
---

# Writing Strategy

## Core Workflow

Use this skill to recommend how to structure a piece of writing, not to draft the full article unless the user asks for the full draft.

1. Infer the user's input language. Output strategy names, overview, rationale, and outline in that language. Use the exact Korean strategy name for Korean input and the exact English strategy name for English input. Keep both names in references for lookup stability, but do not show bilingual paired names unless the user explicitly asks.
2. Extract the writing situation: topic, source material, purpose, intended reader, desired tone, length, and any constraints. If key details are missing, make light assumptions and proceed; ask only when the strategy choice would be genuinely risky.
3. Load [references/index.md](references/index.md) for selection cues. Shortlist 4-6 plausible strategies across different narrative modes.
4. Apply the generic-frame guard before choosing: do not default to `Problem → Solution`, `Status → Problem → Solution`, `Problem → Analysis → Solution → Outcome`, `Introduction → Body → Conclusion`, `Goal → Obstacle → Solution`, or `Need → Solution → Satisfaction` unless the user's material clearly demands a direct fix, status report, diagnostic proposal, or standard essay.
5. Choose one best strategy and 2-3 alternatives. Read only the detailed reference files for the chosen strategy and the alternatives.
6. Produce a Markdown response with the recommended strategy, a short fit rationale, and a complete article outline or table of contents adapted to the user's topic. Then show the alternative strategies in the same output language and invite the user to choose one if they want the outline reframed.

## Output Shape

For Korean input, use this order:

```markdown
## 추천 글쓰기 전략
**정확한 한국어 전략명**

선택 이유: ...

## 글의 전체 구조
1. ...
2. ...

## 대안 전략
- **정확한 한국어 전략명**: ...
- **정확한 한국어 전략명**: ...
```

For English input, use this order:

```markdown
## Recommended Writing Strategy
**Exact English Strategy Name**

Why it fits: ...

## Article Outline
1. ...
2. ...

## Alternative Strategies
- **Exact English Strategy Name**: ...
- **Exact English Strategy Name**: ...
```

Keep the outline specific to the user's material. Do not return a generic template with placeholder-only headings. If the user provides several materials, weave them into the section headings or section notes.

## Strategy Names

The exact strategy names are:

- [핵심 3가지 포인트 강조 / 3 Key Points](references/3_key_points.md)
- [5 WHY 분석 / 5 Whys Analysis](references/5_whys_analysis.md)
- [유사 사례 → 비교 분석 → 시사점 / Analogy → Comparison → Takeaway](references/analogy_comparison_takeaway.md)
- [주목 → 관심 → 욕구 → 행동 / Attention → Interest → Desire → Action (AIDA)](references/attention_interest_desire_action_aida.md)
- [변화 전 → 변화 후 구조 / Before → After](references/before_after.md)
- [변화 전 → 변화 후 → 다음 과제 / Before → After → Next Challenge](references/before_after_next_challenge.md)
- [여정 기반 구조 / Before → Journey → After](references/before_journey_after.md)
- [사례 → 분석 → 시사점 / Case → Analysis → Implication](references/case_analysis_implication.md)
- [원인 → 결과 구조 / Cause → Effect](references/cause_effect.md)
- [도전 → 전략 → 성과 / Challenge → Strategy → Result](references/challenge_strategy_result.md)
- [인물 중심 이야기 / Character-Driven Story](references/character_driven_story.md)
- [비교 → 선택 구조 / Compare → Decide](references/compare_decide.md)
- [경쟁사 비교 → 자사 강점 / Competitor Comparison → Own Strength](references/competitor_comparison_own_strength.md)
- [컨셉 → 표현 사례 → 적용 팁 / Concept → Expression → Tips](references/concept_expression_tips.md)
- [컨셉 소개 → 기능 설명 → 사용 예시 / Concept → Features → Use Case](references/concept_features_use_case.md)
- [논란 → 다각도 분석 → 제안 / Controversy → Analysis → Proposal](references/controversy_analysis_proposal.md)
- [고객 이야기 중심 / Customer-Centric Story](references/customer_centric_story.md)
- [불만 → 대안 → 변화 / Dissatisfaction → Alternative → Transformation](references/dissatisfaction_alternative_transformation.md)
- [반전 구조 (예상 깨기 → 새로운 관점) / Expectation Break → New Perspective](references/expectation_break_new_perspective.md)
- [경험 → 교훈 → 적용 / Experience → Lesson → Application](references/experience_lesson_application.md)
- [사실 → 인사이트 → 실행 구조 / Fact → Insight → Action](references/fact_insight_action.md)
- [사실 → 해석 → 논평 / Fact → Interpretation → Commentary](references/fact_interpretation_commentary.md)
- [실패 → 극복 → 성공 사례 / Failure → Overcome → Success](references/failure_overcome_success.md)
- [특징 → 장점 → 혜택 구조 / Feature → Advantage → Benefit (FAB)](references/feature_advantage_benefit_fab.md)
- [목표 → 장애물 → 극복 방안 / Goal → Obstacle → Solution](references/goal_obstacle_solution.md)
- [한 줄 메시지 → 근거 나열 / Headline → Supporting Points](references/headline_supporting_points.md)
- [주목 → 메시지 → 행동 요청 / Hook → Message → Call-to-Action](references/hook_message_call_to_action.md)
- [서론 → 본론 → 결론 / Introduction → Body → Conclusion](references/introduction_body_conclusion.md)
- [이슈 → 쟁점 → 결론 / Issue → Debate → Conclusion](references/issue_debate_conclusion.md)
- [키워드 나열 → 의미 부여 / Keywords → Meaning](references/keywords_meaning.md)
- [시장 분석 → 기회 포착 → 실행 계획 / Market → Opportunity → Execution](references/market_opportunity_execution.md)
- [오해 → 진실 → 확신 / Misunderstanding → Truth → Conviction](references/misunderstanding_truth_conviction.md)
- [니즈 → 솔루션 → 만족 구조 / Need → Solution → Satisfaction](references/need_solution_satisfaction.md)
- [관찰 → 패턴 → 인사이트 / Observation → Pattern → Insight](references/observation_pattern_insight.md)
- [고통 → 제안 → 기대 효과 / Pain → Claim → Gain](references/pain_claim_gain.md)
- [과거 → 현재 → 미래 구조 / Past → Present → Future](references/past_present_future.md)
- [현상 → 인사이트 → 대안 제시 / Phenomenon → Insight → Proposal](references/phenomenon_insight_proposal.md)
- [문제 → 분석 → 해결책 → 기대 효과 / Problem → Analysis → Solution → Outcome](references/problem_analysis_solution_outcome.md)
- [문제 → 해결 구조 / Problem → Solution](references/problem_solution.md)
- [의문 → 실험 → 결론 / Question → Experiment → Conclusion](references/question_experiment_conclusion.md)
- [질문 → 탐색 → 발견 / Question → Exploration → Discovery](references/question_exploration_discovery.md)
- [반응 유도형 (질문 → 상상 → 정리) / Question → Imagination → Resolution](references/question_imagination_resolution.md)
- [인용 → 해석 → 적용 / Quote → Interpretation → Application](references/quote_interpretation_application.md)
- [현황 → 문제점 → 해결책 / Status → Problem → Solution](references/status_problem_solution.md)
- [SWOT → 전략 → 실행 / SWOT → Strategy → Execution](references/swot_strategy_execution.md)
- [긴장 → 이완 → 결론 / Tension → Relief → Resolution](references/tension_relief_resolution.md)
- [시간 흐름 기반 전개 / Time-Based Narrative](references/time_based_narrative.md)
- [트렌드 → 사례 → 실행 / Trend → Example → Action (TEA)](references/trend_example_action_tea.md)
- [트렌드 → 기회 → 대응 전략 / Trend → Opportunity → Strategy](references/trend_opportunity_strategy.md)
- [관점 제시 → 근거 제시 → 설득 / Viewpoint → Evidence → Persuasion](references/viewpoint_evidence_persuasion.md)
- [비전 → 계획 → 실행 / Vision → Plan → Action](references/vision_plan_action.md)
- [현장 목소리 → 인사이트 / Voice from Field → Insight](references/voice_from_field_insight.md)
- [고객의 말 → 공감 → 제안 / Voice of Customer → Empathy → Proposal](references/voice_of_customer_empathy_proposal.md)
- [왜 → 무엇 → 어떻게 / Why → What → How](references/why_what_how.md)

Referenced files: 57 — file references are metadata, not package contents.