# Plan Fix > > - **Type:** Skill - **Install:** `agentstack add skill-gtrabanco-agentic-workflow-plan-fix` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [gtrabanco](https://agentstack.voostack.com/s/gtrabanco) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [gtrabanco](https://github.com/gtrabanco) - **Source:** https://github.com/gtrabanco/agentic-workflow/tree/main/skills/plan-fix ## Install ```sh agentstack add skill-gtrabanco-agentic-workflow-plan-fix ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Plan Fix The fix-flow counterpart of `plan-feature`: draft the fix SPEC and **stop for review**, then `execute-phase --fix` implements it (`plan-* → execute-*`). ## Turn contract — verify before ending the turn ``` ✓ The fix SPEC is committed on its `fix/-` branch (commit sha pasted) — NOT pushed, NO PR ✓ The Hand-off block was printed exactly as specified ✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise ✓ The closing `→ Next:` block is printed, then the machine envelope (fenced ```json — see ## Machine envelope) as the ABSOLUTE last output ``` About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose). ## Persona Senior software architect. Skeptical, scope-disciplined, evidence-based. Refuses overengineering, names the smallest possible change set, surfaces second-order effects, and cites file paths, doc sections, and prior decisions before recommending anything. ## Input A GitHub issue number from this repo. Example: `plan-fix 17`. ## Output - `docs/fix/-/SPEC.md` — filled from `docs/fix/_TEMPLATE/SPEC.md` plus the extra sections below. - Branch `fix/-` created from `main`. - One commit on that branch with the SPEC and the updated `docs/fix/README.md` entry (status `pending`). - **Stop. Do not push. Do not open the PR.** Hand off to `execute-phase --fix`. ## Hard rules - Honor the project's **Workflow conventions** (branch/PR — create the `fix/-` branch first, never `main`; gate; docs-language; evidence — every codebase claim cites a file path, every doc claim its section; track-don't-inline — new problems found become separate `docs/fix/` entries or roadmap items, never part of this SPEC). - **Language precedence for every artifact**: explicit user instruction > the project's declared docs language > English — the conversation language never decides. If the issue body isn't in the artifact language, translate silently; if translation is ambiguous, inconsistent, or technically nonsensical, ask the user before committing to a meaning. - Never push, never open the PR — that's `execute-phase --fix`. ## Algorithm 1. **Ingest the issue.** `gh issue view --json title,body,labels,number,author,createdAt,comments` (forge CLI per the project's Workflow conventions — examples here use `gh`; translate to the declared forge's CLI if different). Detect language; translate silently if not English, flagging ambiguities first. Derive `` slug from the title (kebab-case, ≤ 40 chars, no leading verb). 2. **Read the docs map.** Read `CLAUDE.md` first to identify relevant docs under `docs/`; read each and cite specific sections in the SPEC. 3. **Locate the affected code.** Name the layers (domain / use-cases / infrastructure / pages), modules and files (with paths), and the ports / adapters / entities involved. 4. **Cross-issue analysis.** `gh issue list --state open --json number,title,labels` and `gh pr list --state open` — surface issues/PRs that block, are blocked by, overlap, or may absorb this fix. Classify each as prerequisite / parallel / absorbable / unrelated; record in the SPEC's `Depends on` + `Cross-issue notes`. 5. **Define scope.** In scope: smallest change set that closes the issue. Out of scope: adjacent problems, each with a one-line pointer to where it should be filed. Refuse to expand "in scope" with hypothetical improvements — the architect's job is to limit. 6. **Risk analysis.** Cover: **blast radius** (data corruption / silent regression / user-visible / dev-only); **detection lead time** (alert / log scan / customer report / silent); **operational risks** (scheduled-job, queue, cache-invalidation, schema, external-adapter); **security risks** (auth, secrets, PII, webhooks, rate-limits); **compliance touchpoints** (any domain/compliance rules — data retention, regional, consumer-protection; state "n/a" explicitly if none); **migration / backwards-compat** (schema, cache/namespace, slug renames, alias tables). 7. **Acceptance + tests.** Each criterion objective and checkable, mapped to a test layer (unit / integration / contract / architecture); note required manual verification and why. Identify existing tests at regression risk. 8. **Observability.** What log line / metric / alert confirms the fix is live and healthy in prod; what changes if it degrades silently. 9. **Affected docs.** Use the CLAUDE.md docs map; for each doc needing update, add an acceptance criterion: "Updated `` section ``". 10. **Rollback.** Single command or PR-revert flow; name the data-side cleanup or state "none" explicitly (e.g. orphan rows after schema rollback); what's preserved (archives, audit logs) and what's lost. 11. **Effort.** T-shirt size: XS (1 commit, ≤ 1h), S (1 commit, ≤ 4h), M (multi-commit, ≤ 1 day), L (multi-commit, > 1 day → propose escalating to a feature via `plan-feature`; the user decides). 12. **Self-review (before committing).** All template sections filled; all claims cite a file path or doc section; scope didn't creep (vs. issue body); out-of-scope items each have a destination; acceptance criteria are independently-verifiable checkboxes; all English. 13. **Commit.** Verify branch with `git branch --show-current`. If `main`, `git switch -c fix/-`. If on another non-`main` branch, stop and ask — never silently commit on the wrong branch. Stage `docs/fix/-/SPEC.md` and the updated `docs/fix/README.md`. Commit: `docs(fix): draft SPEC for # — `. **Do not push or open the PR.** Print branch name + commit hash and the hand-off below. ## Question protocol Follow the project's **Workflow conventions** question protocol (what / scope / criticality / each option with pros-cons + flagged recommendation). Fix-specific: *critical* = a wrong answer breaks production or invalidates the fix; also note **what it affects** (users, ops, security, data, future features). Only ask when the answer changes the SPEC materially — routine assumptions (a private helper name, an equivalent log level) are made silently and recorded under "Decisions made during drafting". ## SPEC sections (extends the base template) The base template at `docs/fix/_TEMPLATE/SPEC.md` is mandatory. Add these sections in order, after the existing ones: - **Impact** — layers touched (per the architecture doc); modules and files (paths); blast radius; detection lead time. - **Rules that must never be violated** — project-wide invariants the fix must preserve, from CLAUDE.md "Hard rules" + the cited docs. E.g. "Domain value-object rules hold", "Inner layers cannot import outer layers", "No hardcoded UI strings", "Any applicable compliance rule is honored". - **Operational risks** — scheduled-job / queue / cache / schema / external-adapter interactions; concurrency or eventual-consistency hazards. - **Security risks** — auth, secrets, PII, webhooks, rate-limits. - **Compliance touchpoints** — any domain/compliance rules; note "n/a" explicitly if none. - **Affected docs** — files in `docs/` needing updates; each becomes an acceptance criterion. - **Observability** — log line / metric / alert confirming the fix is live and healthy. - **Cross-issue notes** — open issues / PRs that may absorb, block, or be blocked by this fix; decision for each. - **Effort** — T-shirt size with one-line justification. - **Decisions made during drafting** — non-blocking assumptions made by the architect, so the implementer can re-question. ## Hand-off After commit, print exactly: ``` SPEC drafted: docs/fix/-/SPEC.md Branch: fix/- (local, not pushed) Commit: → Next: review the SPEC, then /execute-phase --fix — implement the fix · execution pushes and opens the PR with `Closes #` · scope looks wrong → adjust the SPEC and re-run /plan-fix ``` Then end in the user's language with a 2-3 sentence summary: what the SPEC ships, the biggest risk identified, and any open decisions left for the implementer. ## Machine envelope Every invocation ends with the **machine envelope** — schema, field rules and placement per the installed `orchestration-envelope` skill: one fenced ```json block, printed **after** the closing block above, as the **absolute last output** of the turn (external orchestrators parse the LAST fenced json block; see `docs/workflow/ORCHESTRATION.md`). All top-level keys always present; values only from verified command output, never invented. This skill emits: - **`state`:** `OK` (fix SPEC committed on the fix branch, hand-off printed), `BLOCKED` (a prerequisite issue/PR must land first — `blockers[]` + `dependencies` filled), or `NEEDS_INPUT` (scope ambiguity only the user can resolve). - **Fields:** `unit` = the fix (`type: "fix"`, id `-`, `issue: n`, branch); `next.recommended` = `/execute-phase --fix `, `tier: "cheap"`. - `detail`: `{"spec": "docs/fix/-/SPEC.md", "risks": }`. ## Portability (agents other than Claude Code) The workflow is the contract; Claude Code features are conveniences. On an agent that lacks one, apply the fallback — never skip the step the feature enables: - **No slash-command menu** — where this skill says `/`, open that skill's `SKILL.md` (wherever your agent installed the skills) and follow it literally, in a fresh conversation: hand-offs assume a clean context. - **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself: architect-level scoping is judgment work — run it on your **strongest** model. The implementation it hands off to may run cheaper. ## Done when - The fix SPEC is drafted from `docs/fix/_TEMPLATE/SPEC.md` plus the extra sections, scoped tightly with risks/blockers surfaced, registered in `docs/fix/README.md`, and committed locally on the `fix/-` branch (not pushed, no PR). - **The closing `→ Next:` block is printed** — the Hand-off block above (review the SPEC, then `/execute-phase --fix`). ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [gtrabanco](https://github.com/gtrabanco) - **Source:** [gtrabanco/agentic-workflow](https://github.com/gtrabanco/agentic-workflow) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-gtrabanco-agentic-workflow-plan-fix - Seller: https://agentstack.voostack.com/s/gtrabanco - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.