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`.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 1.6 KB |
| SKILL.md | skill md | 5.7 KB |
| agents/openai.yaml | config | 436 B |
| scripts/create_github_task_from_diff.pyexecutable | script | 12.9 KB |
SKILL.md
View on GitHub---
name: agile-github-task-from-diff
description: 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`.
models:
claude: sonnet # medium-complexity; diff analysis + issue authoring across layers
copilot: auto
codex: gpt-5.4
---
# 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](#rename-branch-after-creation).
## Script
Use `scripts/create_github_task_from_diff.py`.
```bash
# 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 `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`](../git-commit-push-pr/SKILL.md) 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
| 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
- `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`.
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: 471k | Updated | Claude CodeCodex | Verified | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |