Tutorial Overview
Series index: Superpowers Tutorial Series
This tutorial covers two Superpowers “wrap-up” skills: verification-before-completion, which ensures the work is actually done, and finishing-a-development-branch, which guides how to integrate the result.
What you will learn
- ✅ Verification strategies for
verification-before-completion - ✅ How to prove success with evidence instead of assertions
- ✅ The decision flow for
finishing-a-development-branch - ✅ Criteria for choosing merge, PR, or cleanup
- ✅ How to close the loop on a full development cycle
verification-before-completion Skill
Why verify?
The problem with assertion-based completion
flowchart LR
A[Finish the work] --> B["Claim it's done"]
B --> C["Is it really?"]
C --> D[No evidence]
D --> E[Trust issue]
E --> F[Need to recheck]
style B fill:#ffcccc
style D fill:#ffcccc
style E fill:#ffcccc
The advantage of evidence-based completion
flowchart LR
A[Finish the work] --> B[Run verification commands]
B --> C[Collect output evidence]
C --> D[Present the evidence]
D --> E[Build trust]
E --> F[Merge smoothly]
style B fill:#e8f5e9
style C fill:#e8f5e9
style D fill:#e8f5e9
When it triggers
verification-before-completion triggers automatically in these scenarios:
- Before claiming completion - when preparing to report that a task is done
- Before committing code - before a commit or push
- Before creating a PR - before requesting merge
- After fixing a bug - before closing the issue
Core principles
verification:
principles:
- "Evidence beats assertion"
- "Repeatable verification"
- "Automation first"
- "Full coverage of acceptance criteria"
anti_patterns:
- "I think it should be fine"
- "I tested it manually"
- "It looks right"
- "It should be okay, right?"
Verification strategies
Strategy 1: Test verification
# ❌ Assertion
"All tests passed"
# ✅ Evidence
$ pytest tests/ -v --tb=short
===================== test session starts =====================
collected 47 items
tests/test_tag_model.py::test_tag_creation PASSED
tests/test_tag_model.py::test_slug_generation PASSED
tests/test_tag_api.py::test_get_tags_list PASSED
...
===================== 47 passed in 12.34s =====================
Test pass rate: 100% (47/47)
Strategy 2: Functional verification
# ❌ Assertion
"The feature works"
# ✅ Evidence
$ curl -X GET http://localhost:8000/api/tags | jq
[
{
"id": 1,
"name": "Python",
"slug": "python",
"created_at": "2026-02-28T10:00:00Z"
},
{
"id": 2,
"name": "AI",
"slug": "ai",
"created_at": "2026-02-28T10:05:00Z"
}
]
API response is normal and returns 2 tags
Strategy 3: Quality verification
# ❌ Assertion
"The code quality is good"
# ✅ Evidence
$ npm run lint
> lint
> eslint src/ --max-warnings=0
✖ 0 problems (0 errors, 0 warnings)
$ npm run typecheck
> typecheck
> tsc --noEmit
No type errors found.
Lint: ✅ 0 problems
TypeScript: ✅ no errors
Strategy 4: Performance verification
# ❌ Assertion
"Performance is good"
# ✅ Evidence
$ ab -n 1000 -c 10 http://localhost:8000/api/tags/
Benchmarking localhost (be patient).....done
Server Software: uvicorn
Server Hostname: localhost
Server Port: 8000
Document Path: /api/tags/
Document Length: 1024 bytes
Concurrency Level: 10
Time taken for tests: 1.234 seconds
Complete requests: 1000
Failed requests: 0
Requests per second: 810.37 [#/sec] (mean)
Time per request: 12.340 [ms] (mean)
Time per request: 1.234 [ms] (mean, across all concurrent requests)
Performance metrics:
- RPS: 810.37
- Average latency: 12.34ms
- Failed requests: 0
Verification checklist
## Completion Verification Checklist
**Task**: Tag system implementation
### Functional verification
- [ ] All unit tests pass
```bash
$ pytest tests/unit/ -v
45 passed
-
All integration tests pass
$ pytest tests/integration/ -v 12 passed -
Manual API endpoint test
$ curl http://localhost:8000/api/tags [{"id":1,"name":"Python"}]
Code quality
-
Lint passes
$ npm run lint 0 problems -
Type check passes
$ tsc --noEmit No errors -
Code formatting is clean
$ prettier --check src/ All files formatted correctly
Performance verification
-
Response time < 100ms
$ ab -n 100 http://localhost:8000/api/tags Time per request: 23.45ms -
No memory leaks
$ memory_profiler Memory usage stable at 128MB
Security verification
-
No SQL injection risk
$ sqlmap --test No vulnerabilities found -
Input validation is complete
$ pytest tests/security/ All security tests passed
Documentation verification
- README updated
- API docs generated
- Changelog updated
Verification conclusion: ✅ All checks passed, ready to submit
### What to do when verification fails
```markdown
## Verification Failure Example
**Verification item**: Performance test
**Expected**: Response time < 100ms
**Actual**:
```bash
$ ab -n 1000 http://localhost:8000/api/tags
Time per request: 234ms
Analysis:
- Performance is below target (234ms > 100ms)
- Cause: database query does not use an index
Fix plan:
- Add an index to the tags table
- Optimize the N+1 query
- Verify again
Status: ⏸️ Blocked, re-verify after fixing
## `finishing-a-development-branch` Skill
### When it triggers
`finishing-a-development-branch` triggers automatically in these scenarios:
1. **All tasks are done** - the implementation plan is complete
2. **Ready to integrate** - the work needs to be merged into the main branch
3. **Worktree cleanup** - you need to decide what to do with the worktree
### Decision flow
```mermaid
flowchart TD
A[All tasks done] --> B[finishing-a-development-branch]
B --> C{Verification passed?}
C -->|No| D[Fix the problems]
D --> C
C -->|Yes| E{How should it be integrated?}
E -->|Merge directly| F[merge to main]
E -->|Need review| G[Create PR]
E -->|Experimental feature| H[Keep branch]
E -->|Discard feature| I[Clean up and delete]
F --> J[Clean worktree]
G --> J
H --> K[Keep worktree]
I --> L[Delete worktree]
style B fill:#e1f5ff
style F fill:#e8f5e9
style G fill:#e8f5e9
style J fill:#fff3e0
style L fill:#ffebee
Integration options in detail
Option 1: Merge directly into main
Use when:
- It is a personal project
- The work has been thoroughly reviewed
- It is an urgent fix
- The team has a high level of trust
Process:
# 1. Make sure you are on the latest main branch
git checkout main
git pull origin main
# 2. Merge the feature branch
git merge feature/tag-system --no-ff
# 3. Write a meaningful merge message
git merge feature/tag-system --no-ff -m "
feat: implement tag system
Features:
- Tag CRUD operations
- Article-tag relationships
- Tag filtering queries
Technical details:
- Use a many-to-many relationship
- Add full test coverage
- Follow REST API conventions
Closes: #123
"
# 4. Push
git push origin main
# 5. Clean up the worktree
git worktree remove ../theme-stack-blog-feature-tag
git branch -d feature/tag-system
Option 2: Create a Pull Request
Use when:
- It is a team project
- Formal review is required
- The feature is important
- CI/CD verification is needed
Process:
# 1. Push to remote
git push origin feature/tag-system
# 2. Create the PR (GitHub CLI)
gh pr create \
--title "feat: implement tag system" \
--body "
## Summary
Implement a complete tag system that supports article categorization and filtering.
## Changes
- Add Tag model and migration
- Implement tag API endpoints
- Add front-end tag components
- Full test coverage
## Testing
- [x] Unit tests (57)
- [x] Integration tests (12)
- [x] Manual tests passed
## Screenshots
## Related issue
Fixes #123
" \
--label "feature" \
--reviewer teammate1,teammate2
# 3. Wait for review and CI
# 4. Clean up after merge
git branch -d feature/tag-system
git worktree remove ../theme-stack-blog-feature-tag
Option 3: Keep the branch and continue testing
Use when:
- The feature is experimental
- More verification is needed
- Other unfinished features are a dependency
- It is a long-lived feature branch
Process:
# Keep the current state and keep developing
# Sync with main regularly
git checkout main
git pull origin main
git checkout feature/tag-system
git rebase main
# Continue testing in the worktree
cd ../theme-stack-blog-feature-tag
# Keep developing and testing
Option 4: Clean up and delete
Use when:
- The feature was rejected
- The technical approach is not viable
- Requirements changed
- The experiment failed
Process:
# 1. Record the lesson learned (important!)
cat >> .project/learnings.md << EOF
## Tag system attempt - deprecated
Date: 2026-02-28
Reason:
- Performance did not meet target (queries were too slow)
- The team decided to use a third-party service
Lessons:
- Verify performance early
- Consider ready-made solutions
Related code locations:
- Git branch: feature/tag-system (deleted)
- Design doc: .project/designs/tag-system.md
EOF
# 2. Delete the branch
git branch -D feature/tag-system
# 3. Remove the worktree
git worktree remove ../theme-stack-blog-feature-tag
# 4. Remove the remote branch (if it was pushed)
git push origin --delete feature/tag-system
Cleanup checklist
## Branch Cleanup Checklist
### Before merge
- [ ] All tests pass
- [ ] Code review passed
- [ ] No merge conflicts
- [ ] Documentation updated
### Merge operation
- [ ] Choose the correct merge strategy
- [ ] Write a clear merge message
- [ ] Link the related issue
### After merge cleanup
- [ ] Delete the local branch
- [ ] Delete the remote branch
- [ ] Clean up the worktree
- [ ] Update project status
### Follow-up actions
- [ ] Deploy to the staging environment
- [ ] Notify relevant people
- [ ] Monitor key metrics
- [ ] Prepare a rollback plan
Full Development Cycle Example
End-to-end flow
flowchart TD
Start[Requirement raised] --> B1[brainstorming]
B1 --> B2[Design document]
B2 --> B3[writing-plans]
B3 --> B4[Implementation plan]
B4 --> B5[using-git-worktrees]
B5 --> B6[Create worktree]
B6 --> B7[subagent-driven-development]
B7 --> T1[Task 1 done]
B7 --> T2[Task 2 done]
B7 --> T3[Task N done]
T1 --> R1[requesting-code-review]
T2 --> R2[requesting-code-review]
T3 --> R3[requesting-code-review]
R1 --> V1[verification]
R2 --> V2[verification]
R3 --> V3[verification]
V1 --> F[finishing-a-branch]
V2 --> F
V3 --> F
F --> Merge{Merge decision}
Merge -->|PR| PR[Create PR]
Merge -->|Direct| Direct[Merge directly]
PR --> Clean[Clean up]
Direct --> Clean
Clean --> End[Done]
style B1 fill:#e1f5ff
style B3 fill:#e1f5ff
style B5 fill:#e8f5e9
style B7 fill:#fff3e0
style F fill:#f3e5f5
Timeline example
Day 1 - Design and planning
09:00 - brainstorming starts
10:30 - design document completed
11:00 - writing-plans starts
12:00 - implementation plan completed
Day 1-2 - Development
13:00 - using-git-worktrees creates the environment
13:30 - subagent-driven-development starts
14:00 - Tasks 1-3 done + review
16:00 - Tasks 4-6 done + review
Day 2 10:00 - all tasks done
Day 2 - Verification and integration
10:30 - verification-before-completion
11:00 - fix issues found during verification
12:00 - verification passes again
14:00 - finishing-a-development-branch
14:30 - create PR
15:00 - code review
16:00 - fix review feedback
17:00 - PR merged
17:30 - clean up worktree
Total time: about 1.5 days
Best Practices
1. Automate verification
# .github/workflows/verification.yml
name: Verification
on: [push, pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run tests
run: pytest tests/ -v
- name: Run lint
run: npm run lint
- name: Type check
run: tsc --noEmit
- name: Performance test
run: pytest tests/performance/ -v
- name: Security scan
run: bandit -r src/
2. Verification report template
## Verification Report
**Feature**: Tag system
**Date**: 2026-02-28
**Verifier**: AI Assistant
### Test summary
Tests: 57 passed, 0 failed Coverage: 92.3% Build: ✅ Success
### Key metrics
| Metric | Expected | Actual | Status |
|-----|------|------|------|
| Response time | <100ms | 23ms | ✅ |
| Error rate | <0.1% | 0% | ✅ |
| Coverage | >85% | 92.3% | ✅ |
### Manual verification
- [x] Tag creation
- [x] Tag list display
- [x] Tag filtering
- [x] Error handling
**Conclusion**: ✅ Verification passed, ready to merge
3. Merge strategy selection
# Choose based on project type
merge_strategy:
# Personal project - merge directly
personal:
strategy: merge
require_review: false
# Small team - lightweight PR
small_team:
strategy: pr
require_review: true
reviewers: 1
# Large team - formal PR
enterprise:
strategy: pr
require_review: true
reviewers: 2
require_ci: true
require_security_scan: true
Summary
These two skills ensure development work has a proper beginning and end:
verification-before-completion- let evidence speakfinishing-a-development-branch- make the right integration decision
Key takeaways
- ✅ Verification beats assertion
- ✅ Automation-first verification
- ✅ Choose the integration strategy based on the scenario
- ✅ Cleanup is a required step
Quick verification checklist
□ Tests pass (with output evidence)
□ Lint passes (with output evidence)
□ Type check passes (with output evidence)
□ Performance meets target (with benchmark)
□ Security checks pass (with scan report)
□ Documentation updated (with diff)
Series navigation:
- ← Previous: Tutorial 8:
subagent-driven-developmentand Parallel Tasks - → Next: Tutorial 10:
writing-skills- Create Your Own Skills - Back: Series Index