Skip to content

generic-automation-and-it/smooth-ai-stockanalysis / .agents/skills/agile-github-task-from-diff

agile-github-task-from-diff

Verified

Create a GitHub Task (sub-issue) from the current git diff vs main and link it as a sub-issue of a parent Feature in the local GitHub SmoothAiStockAnalysis. Use when Codex needs to summarize branch changes into a horizontally sliced task with acceptance criteria and create it via `gh`.

Task From Diff

Overview

Generate a GitHub Task issue from the current branch diff versus main. The task is horizontally sliced — scoped to one technical layer (backend, tests, docs, ai-tooling, config) — and added to the local GitHub Project as a sub-issue of a vertically sliced parent Feature issue.

Workflow

  1. Ensure the repo has an up-to-date origin/main (or override the base ref).
  2. Run a dry run to review the generated title, body, and acceptance criteria.
  3. Create the task issue, add it to the project, and optionally link it as a sub-issue of the Feature.
  4. Rename the current branch to match the <type>/<issue>-short-description naming standard using the newly created issue number — see Rename Branch After Creation.

Script

Use scripts/create_github_task_from_diff.py.

# Preview (dry run)
python3 .agents/skills/agile-github-task-from-diff/scripts/create_github_task_from_diff.py --dry-run

# Create task, add to project #1, link as sub-issue of Feature #42 (number or issue URL)
python3 .agents/skills/agile-github-task-from-diff/scripts/create_github_task_from_diff.py --feature-issue 42

# Combine flags from the Inputs table as needed, e.g.:
python3 .agents/skills/agile-github-task-from-diff/scripts/create_github_task_from_diff.py \
  --feature-issue 42 --base-ref main --title "Add persistence layer tests" --open

Inputs

FlagDefaultDescription
--feature-issue(none)Parent Feature issue — accepts an issue number (42) or a full GitHub issue URL (https://github.com/.../issues/42). When set, the task is linked as a sub-issue.
--title(generated)Override the auto-generated task title.
--repo(from remote)GitHub repo as owner/repo. Auto-detected when omitted.
--project1GitHub project number under the org.
--no-project—Create the issue only; skip adding it to any GitHub SmoothAiStockAnalysis.
--org(repo owner)GitHub org that owns the project. Defaults to the repo owner detected from the git remote.
--labeltaskLabel applied to the created issue.
--base-reforigin/main → mainOverride base ref for the diff.
--dry-run—Print output without creating anything.
--open—Open the created issue in the browser.

Behavior

  • Computes the diff from merge-base between HEAD and the base ref.
  • Classifies the diff into horizontal layers: backend, tests, documentation, ai-tooling, config, general.
  • Builds a title from the detected layers and affected top-level areas.
  • Generates an acceptance criteria checklist based on touched paths.
  • Creates the issue via gh issue create.
  • Adds the issue to the GitHub Project via gh project item-add.
  • Links the issue as a sub-issue of the parent Feature via the GitHub REST API (gh api POST /repos/.../sub_issues).

Rename Branch After Creation

After the task issue is created, rename the current local branch so it conforms to the <type>/<issue>-short-description standard enforced by the git-commit-push-pr skill and .agents/rules/git/git-policy.instructions.md (the source of truth). This guarantees the downstream PR title and Closes #<issue> link can be derived from the branch name.

The script prints a ready-made suggestion after creating the issue (Suggested branch rename: git branch -m <type>/<issue>-<slug>) — it derives <type> from the dominant horizontal layer, <issue> from the new issue number, and the slug from the task title. Run that command (no commit/push is performed by this skill). Override the <type> if the diff is better described by fix/refactor than the layer mapping suggests.

Notes:

  • Skipped on --dry-run — nothing is created, so there is no issue number to rename against.
  • If a conforming <type> or slug cannot be determined, stop and ask the user — do not guess, matching the format-enforcement rule in git-policy.instructions.md.
  • If the branch was already pushed, the rename stays local; the subsequent git-commit-push-pr run pushes the renamed branch (its --issue handling parses the same number back out of the branch name).

Vertical vs Horizontal Slicing

ConceptOwnerDescription
Feature (parent)ProductVertically sliced — one complete user-facing capability across all layers.
Task (this skill)EngineerHorizontally sliced — one technical layer of work from the diff (e.g. just the backend changes, or just the test changes).

Requirements

  • gh CLI authenticated with a token that has repo and project scopes.
  • git available in the repo.
  • The task label must exist in the target repo (create with gh label create task --color 0075ca).

Troubleshooting

  • If gh issue create fails, run gh auth status to verify authentication.
  • If gh project item-add fails, ensure your token has the project scope (gh auth refresh -s project).
  • If the sub-issue API call fails, the script prints a fallback message; link manually in the GitHub UI.
  • If the diff is empty, ensure your branch contains changes against main or override --base-ref.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexUnverifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 318kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexVerifiedInstall