generic-automation-and-it/smooth-ai-stockanalysis / .agents/skills/agile-github-task-from-diff
agile-github-task-from-diff
VerifiedCreate 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
- Ensure the repo has an up-to-date
origin/main(or override the base ref). - Run a dry run to review the generated title, body, and acceptance criteria.
- Create the task issue, add it to the project, and optionally link it as a sub-issue of the Feature.
- Rename the current branch to match the
<type>/<issue>-short-descriptionnaming 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
| Flag | Default | Description |
|---|---|---|
--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. |
--project | 1 | GitHub 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. |
--label | task | Label applied to the created issue. |
--base-ref | origin/main → main | Override 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
HEADand 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 ingit-policy.instructions.md. - If the branch was already pushed, the rename stays local; the subsequent
git-commit-push-prrun pushes the renamed branch (its--issuehandling parses the same number back out of the branch name).
Vertical vs Horizontal Slicing
| Concept | Owner | Description |
|---|---|---|
| Feature (parent) | Product | Vertically sliced — one complete user-facing capability across all layers. |
| Task (this skill) | Engineer | Horizontally sliced — one technical layer of work from the diff (e.g. just the backend changes, or just the test changes). |
Requirements
ghCLI authenticated with a token that hasrepoandprojectscopes.gitavailable in the repo.- The
tasklabel must exist in the target repo (create withgh label create task --color 0075ca).
Troubleshooting
- If
gh issue createfails, rungh auth statusto verify authentication. - If
gh project item-addfails, ensure your token has theprojectscope (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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 465k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 465k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 318k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |