docs: add general-dev-workflow skill to repo for version control
Stores the canonical general-dev-workflow skill definition alongside the codebase so it travels with the project and can be evolved via normal PRs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,224 @@
|
||||
# General Development Workflow
|
||||
|
||||
This skill guides you through a structured, repeatable development workflow that works across any tech stack and version control platform. The goal is to ensure consistent, high-quality code while reducing context-switching and providing clear checkpoints.
|
||||
|
||||
## The 5-Phase Workflow
|
||||
|
||||
### Phase 1: Plan
|
||||
**Goal**: Define the change clearly before writing code.
|
||||
|
||||
Start by answering:
|
||||
- **What** are you building/fixing? (Brief 1-2 sentence summary)
|
||||
- **Why** does it matter? (Problem it solves, value it adds)
|
||||
- **Scope**: What's included? What's NOT included? (Define boundaries early)
|
||||
- **Success criteria**: How will you know it's done? (Tests pass, performance improves, etc.)
|
||||
- **Dependencies**: Does this require changes elsewhere? Do other features depend on this?
|
||||
- **Risks**: What could go wrong? (Breaking changes, performance issues, etc.)
|
||||
|
||||
**Output**: A clear plan document or issue description ready for the next phase.
|
||||
|
||||
**Checkpoint**: Does the plan make sense? Is scope realistic? Have you thought through edge cases?
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Create Issue (in your VCS)
|
||||
**Goal**: Formally track the work — and the time spent on it — starting from the moment the plan is approved.
|
||||
|
||||
> ⚠️ **Create the issue only after the plan has been reviewed and approved.** The issue marks the official start of implementation, so its creation timestamp doubles as the implementation start time. Do not create it speculatively while the plan is still being discussed.
|
||||
|
||||
Steps:
|
||||
1. **Detect your VCS platform**: GitHub, GitLab, Gitea, or local-only?
|
||||
2. **Create the issue** with:
|
||||
- Title matching your plan summary
|
||||
- Description from Phase 1 (what, why, scope, success criteria)
|
||||
- A `## Time tracking` section at the bottom with `Started: <date/time>` — this lets you measure implementation duration later
|
||||
- Any relevant labels/tags (bug, feature, enhancement, etc.)
|
||||
- Assignment (if applicable)
|
||||
3. **For local-only work**: Create a text file or branch-based tracking if you prefer
|
||||
|
||||
**Output**: Issue link (or local tracking document) that you'll reference in commits and in the PR.
|
||||
|
||||
**Checkpoint**: Can someone else understand the work from this issue? Would they know how to verify it's done?
|
||||
|
||||
> 🕐 **Do not close the issue here.** It stays open until the PR is merged (Phase 5).
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Implement
|
||||
**Goal**: Write code that solves the problem defined in the plan.
|
||||
|
||||
**Before you start coding:**
|
||||
- Create a branch (e.g., `feature/user-auth`, `fix/api-latency`) that references your issue
|
||||
- Name the branch clearly so it's easy to track what you're working on
|
||||
|
||||
**While coding:**
|
||||
- Break work into logical, reviewable commits (not one giant commit)
|
||||
- Write commit messages that explain *why*, not just *what*
|
||||
- Bad: "fix bug"
|
||||
- Good: "fix race condition in event handler by adding mutex lock — prevents duplicate events when rapidly clicking"
|
||||
- Follow the project's code style and conventions
|
||||
- Write code you'd be comfortable having someone else maintain
|
||||
|
||||
**As you finish sections:**
|
||||
- Test locally (Phase 4 will be formal testing, but catch obvious issues early)
|
||||
- If you realize the scope has changed, update your Phase 1 plan and issue
|
||||
|
||||
**Output**: Commits on your branch that are ready for review.
|
||||
|
||||
**Checkpoint**: Does each commit stand alone? Would a reviewer understand why each change was made?
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Test
|
||||
**Goal**: Verify the code works correctly and doesn't break existing functionality.
|
||||
|
||||
**Write tests for your changes:**
|
||||
- Unit tests for individual functions/methods
|
||||
- Integration tests if your code touches multiple systems
|
||||
- Edge case tests (null inputs, boundary conditions, etc.)
|
||||
- Regression tests to ensure you didn't break something else
|
||||
|
||||
**Run existing tests:**
|
||||
- Do all tests pass? Fix failures in Phase 3 code
|
||||
- Check code coverage. Did you test your changes?
|
||||
|
||||
**Manual testing:**
|
||||
- Does the feature work as described in the plan?
|
||||
- Did you test the success criteria from Phase 1?
|
||||
- Test on different inputs/environments if relevant
|
||||
|
||||
**Test results document** (save for Phase 5 PR):
|
||||
- Which tests were added?
|
||||
- What's the coverage? (old → new)
|
||||
- Any manual testing notes
|
||||
- Known limitations or edge cases not yet tested
|
||||
|
||||
**Output**: Passing tests, code coverage report, test summary.
|
||||
|
||||
**Checkpoint**: Can you confidently say the code works? Are there any untested paths you're worried about?
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Create Pull Request
|
||||
**Goal**: Get code reviewed and merged into `main`, and automatically close the tracking issue on merge.
|
||||
|
||||
**Before opening the PR:**
|
||||
- Rebase onto the latest `main`/`master` (avoid merge commits if possible)
|
||||
- Verify all tests still pass
|
||||
- Check for merge conflicts
|
||||
- The PR **must target `main`** (or the project's primary branch) — never merge directly without a PR
|
||||
|
||||
**PR Description** (use this template):
|
||||
```
|
||||
## What
|
||||
Brief summary of the change (one sentence)
|
||||
|
||||
## Why
|
||||
Problem it solves / value it adds (2-3 sentences)
|
||||
|
||||
## Changes
|
||||
- Major code change 1
|
||||
- Major code change 2
|
||||
- (Be specific—help reviewers understand scope)
|
||||
|
||||
## Testing
|
||||
- Tests added: [list test files or test count]
|
||||
- Coverage change: [old % → new %]
|
||||
- Manual testing: [describe what was tested]
|
||||
|
||||
## Risk Assessment
|
||||
- Breaking changes? [yes/no, if yes: explain migration path]
|
||||
- Performance impact? [none/minor/significant]
|
||||
- Closes #<issue-number>
|
||||
|
||||
## Checklist
|
||||
- [ ] All tests passing
|
||||
- [ ] Code review ready
|
||||
- [ ] Documentation updated (if needed)
|
||||
- [ ] No merge conflicts
|
||||
```
|
||||
|
||||
> 🔗 **Always include `Closes #<issue-number>`** in the PR body. On GitHub and Gitea this auto-closes the issue the moment the PR is merged into the target branch — no manual close needed.
|
||||
|
||||
**During review:**
|
||||
- Respond to feedback promptly
|
||||
- If changes are requested, make them and push again (don't force-push)
|
||||
- Ask for clarification if feedback is unclear
|
||||
|
||||
**Merge criteria** (before merging):
|
||||
- ✅ All tests pass
|
||||
- ✅ Approved by at least one reviewer (adapt to your team's policy)
|
||||
- ✅ No unresolved discussions
|
||||
- ✅ No merge conflicts
|
||||
|
||||
**After the PR is merged:**
|
||||
- Verify the issue was automatically closed by the `Closes #N` keyword
|
||||
- If the platform did not auto-close it, close it now and add a comment with the merge commit SHA and the elapsed time (issue `Created` timestamp → merge timestamp)
|
||||
- **Never close the issue before the PR is merged** — an open issue means work is still in progress
|
||||
|
||||
**Output**: Merged PR with clear history and review comments; issue automatically closed.
|
||||
|
||||
**Checkpoint**: Is the code in `main`? Is the issue closed? Did you record the implementation duration in the issue?
|
||||
|
||||
---
|
||||
|
||||
## Workflow Summary (Quick Reference)
|
||||
|
||||
| Phase | Input | Output | Checkpoint |
|
||||
|-------|-------|--------|-----------|
|
||||
| 1. Plan | Problem description | Approved plan document | Scope and success criteria defined? Plan reviewed and approved? |
|
||||
| 2. Issue | **Approved** plan | Issue/ticket link + start timestamp | Is it understandable to others? Issue open (not closed)? |
|
||||
| 3. Implement | Issue/ticket | Commits on feature branch | Are commits logical and well-messaged? |
|
||||
| 4. Test | Code on branch | Passing tests + coverage report | Are edge cases covered? |
|
||||
| 5. PR | Tests passing | PR merged into `main`; issue auto-closed via `Closes #N` | Is `main` updated? Is the issue closed? Duration recorded? |
|
||||
|
||||
---
|
||||
|
||||
## Tips for Success
|
||||
|
||||
**Keep phases focused.** Don't mix planning with implementation. Don't test in Phase 2. This separation helps catch problems early.
|
||||
|
||||
**Commit frequently.** Small commits are easier to review, easier to revert if needed, and easier to understand. Aim for 50-200 lines per commit.
|
||||
|
||||
**Write for your future self.** Six months from now, you'll read your own commits and PRs. Make them clear.
|
||||
|
||||
**Catch blocking issues early.** If Phase 1 reveals something complex or risky, discuss it with your team *before* you code.
|
||||
|
||||
**Adapt to your team.** If your team requires code owners approval, or has a specific PR template, use those instead of the defaults here. The phases stay the same; the details adapt.
|
||||
|
||||
---
|
||||
|
||||
## For Different Platforms
|
||||
|
||||
**GitHub**: Issues are native. Use GitHub's PR template and auto-linking (`Closes #123`).
|
||||
|
||||
**GitLab**: Merge Requests (MRs) replace PRs. Pipeline status is built-in. Use GitLab's merge request template.
|
||||
|
||||
**Gitea**: Similar to GitHub. Use Gitea's PR templates and linking.
|
||||
|
||||
**Local/No Platform**: Create a `.github` folder locally with your own issue and PR templates. Track work via commit messages and branch names.
|
||||
|
||||
---
|
||||
|
||||
## Common Questions
|
||||
|
||||
**Q: Can I skip Phase 2 (create issue)?**
|
||||
A: If you're working solo on a small fix, maybe. But issues are useful for: remembering *why* you made a change, helping others understand work in progress, tracking what's been done, and measuring how long implementation actually takes. Recommended even for solo developers.
|
||||
|
||||
**Q: When exactly should I create the issue?**
|
||||
A: Only after the plan (Phase 1) has been reviewed and approved. The issue creation timestamp marks the official start of implementation and serves as the start of your time-tracking window. Creating it during planning inflates the recorded duration.
|
||||
|
||||
**Q: When should I close the issue?**
|
||||
A: Never close it manually before the PR is merged. Use `Closes #N` in the PR body — the platform (GitHub/Gitea) will close it automatically when the PR merges into the target branch. If auto-close doesn't trigger, close it immediately after merge and note the elapsed time.
|
||||
|
||||
**Q: How do I track implementation time?**
|
||||
A: The issue creation time is your start. The issue close time (= PR merge time) is your end. To make this explicit, add a `## Time tracking` section to the issue body with `Started: <date/time>` when you create it. After merge, update or comment with `Completed: <date/time> — Duration: X hours/days`.
|
||||
|
||||
**Q: What if my plan changes mid-implementation?**
|
||||
A: Update your issue/plan (Phase 1) to reflect the new scope. Let your team know if scope grew significantly.
|
||||
|
||||
**Q: How big should commits be?**
|
||||
A: Aim for "one logical change per commit." If you're changing authentication and fixing a typo, those are two commits. A good rule: can you describe the commit in one clear sentence without "and"?
|
||||
|
||||
**Q: Do I need tests for everything?**
|
||||
A: Write tests for anything that could break. UI color changes? Maybe not. API endpoint behavior? Definitely. If you're unsure, write the test.
|
||||
Reference in New Issue
Block a user