sprint.md

sprint.md

Sprint

Autonomous development session. Follows the CONTRIBUTING.md workflow with pre-authorized decisions — agent pauses only for substantive technical uncertainty, never for process approvals.

Session boundary model: The seam between sessions is the PR. A session ends with all work filed as PRs, tree clean. The next session begins with independent review of those PRs — fresh context, full rigor. The agent never reviews its own work in the same context that wrote it.

Announce

"Starting sprint. Reading turnover and checking project state."

Phase 1: Orient

1a. Read turnover

Check for the most recent file in docs/turnover/. If it exists, read it — this is context from the previous sprint, including the current tier/priority plan.

If no turnover exists, evaluate the issue board and create a plan:

gh issue list --repo stvorg/gist-story-ranker-2 --state open --json number,title,labels --limit 30

Organize by tier/priority. Write the plan into the turnover doc for this session.

If turnover exists but the plan looks stale (issues closed, priorities shifted), update it from the board.

1b. Review and merge open PRs

gh pr list --repo stvorg/gist-story-ranker-2 --state open --json number,title,author,headRefName

1. Fetch and checkout the branch: git fetch fork && git checkout <branch>
2. Run /requesting-code-review — full independent review with fresh context
3. Fix all issues that would improve the code, including minor and nits. Commit fixes.
4. Run /code-simplification on the branch
5. Push fixes: git push fork <branch>
6. Once clean: merge the PR and delete the remote branch
7. Bump version: ./compute-version.sh --ci --update (always patch)

After processing all PRs, return to main:

git checkout main
git pull origin main

1c. Sync and verify

uv sync --all-extras
uv run pytest

If tests fail after merges, diagnose and fix before proceeding.

1d. Clean up

Delete any local branches that have been merged. Ensure working tree is clean.

Phase 2: Work

Follow the CONTRIBUTING.md workflow for each issue. The sprint pre-authorizes these decisions so you can move through without pausing:

Pre-authorized decisions

Step	Decision	Authority
Issue selection	Pick from lowest incomplete tier in plan	Authorized — announce choice, don't ask
Branch creation	Create feature branch from main	Authorized
/brainstorming	When asked "design for approval or information?"	Answer: "information" — present design, proceed unless technically uncertain
/brainstorming	Approach selection	Pick your recommended approach. Only pause if trade-offs are genuinely unclear.
/writing-plans	Plan scope	Write the plan, proceed to execution. Only pause if the scope seems too large for one PR.
/executing-plans	Implementation choices	Make them. Commit to decisions. Only pause if you discover a design flaw mid-implementation.
TDD	Test strategy	Write tests first for Python code. For config/infrastructure, verify after writing.
Commit messages	Wording	Use imperative mood, explain why. Don't ask for approval.
PR creation	Title, body, labels	Write them well. Don't ask for review of PR text.
Ruff lint/format	Fix or ignore	Fix all. Run uv run ruff check --fix . && uv run ruff format . before committing.

What still requires pausing

• Genuine technical uncertainty — two valid approaches with real trade-offs you can't resolve
• Scope creep — you discover the issue is much larger than expected
• Breaking changes — something that would change the API contract or data model in ways not described in the issue
• Blocked — a dependency that prevents progress

Workflow per issue

1. Branch: git checkout -b <type>/<issue>-<slug> main and write .issue file
2. Brainstorm: /brainstorming with issue context (design for information, not approval)
3. Plan: /writing-plans if the issue warrants it (skip for small/obvious changes)
4. Implement: /executing-plans or implement directly. TDD for code. Verify for config.
5. Lint: uv run ruff check --fix . && uv run ruff format .
6. Verify: uv run pytest — all tests pass
7. PR: Push to fork, file cross-fork PR to stvorg/gist-story-ranker-2

git push fork <branch>
gh pr create --repo stvorg/gist-story-ranker-2 \
  --head gist-story-ranker-kathleen:<branch> \
  --base main \
  --title "<title>" \
  --body "$(cat <<'PREOF'
## Summary
<bullets>

Closes #<issue>

## Test plan
<bullets>

🤖 Generated with [Claude Code](https://claude.com/claude-code)
PREOF
)"

8. Next issue: Return to main, pick next issue from plan, repeat

Phase 3: Wrap up

When work is complete or the user signals done:

3a. Leave tree clean

• All work is in filed PRs with branches pushed to fork
• Working tree is on main, clean (git status shows nothing)
• No local-only branches with unpushed work

3b. Write turnover doc

Create or update docs/turnover/YYYY-MM-DD.md (append sequence number if file exists):

# Sprint Turnover — YYYY-MM-DD

## Plan
<current tier/priority plan — what's next, what's blocked, what shifted>

## Completed this session
- #N: <what was done>

## Open PRs (ready for review/merge next sprint)
- #N: <branch, status, any notes>

## Notes
- <anything surprising, blockers, or context the next session needs>

3c. Brief summary

Report to user:

• Issues worked: #X, #Y
• PRs filed: #A, #B
• Tests passing: yes/no
• Recommended next:

Process rules (baked in, never ask about these)

• Always patch release — no users yet
• One PR per issue — clean traceability
• Squash merge — one commit per PR in main
• Fork workflow — push to fork remote (gist-story-ranker-kathleen), PR to stvorg/gist-story-ranker-2
• Signed commits — SSH signing already configured, automatic
• Duplicate check before filing issues — gh issue list --search "<keywords>" first
• Follow CONTRIBUTING.md — the sprint optimizes by pre-authorizing decisions, not by skipping steps