Chapter 8. Operations and Improvements — Running the Next Cycle with Issues
Required Read this to follow this stage.One-line summary: Write down improvements and bugs that come to mind after publishing as Issues. One issue becomes the plan for your next cycle. If you write a special keyword like
fixes #numberin a PR, that issue closes automatically when you merge the PR. This is how planning and operations connect.
This chapter is based on the official GitHub docs checked on November 1, 2026. The GitHub screen names are written in English.
What Is an Issue?
An Issue is a record for planning, discussing, and tracking work.[1] It holds anything you want to write down or talk about, like bug reports, new features, or ideas. It is similar to writing "things to discuss next" in the meeting notes in Stage 3.
Issues connect to PRs. When you mention another issue in an issue or a PR, they link together, and if you write a special keyword like fixes in a PR, the related issue closes automatically.[2]
fixes #issue-numberThe issue number appears next to the issue title, like #2. If you created a PR in Chapter 6, your first issue might not be #1, so be sure to check the number on your screen.
When you write an issue, just write the feature you want to build in the title, and write a few lines in the description about what you want to make.[3] For example, the title could be "Show overdue to-dos in red" and the description "I'd like to-dos whose due date is before today to show their text in red."
Quick check
What happens if you write fixes #1 in a PR description?
Organizing with Labels and Boards
As you get more issues, you sort them with labels. Every new repository comes with default labels.[4]
| Label | Meaning |
|---|---|
| bug | An unexpected problem |
| enhancement | A request for a new feature |
| documentation | Improvements to documentation |
Source: GitHub official docs (selected items)[4:1]
Projects are tables, boards, and roadmaps connected to your issues and PRs.[5] On the tutorial's board, each column represents a stage of your work. You move items from Todo → In Progress → Done to see your progress.[6]
You don't need to use all of this from the start. As you saw in Chapter 1, many people start with just one repository and a few issues. It is never too late to start using labels and boards once you have too many issues to see at a glance.
Quick check
Which default GitHub label fits an issue requesting a new feature?
Running One More Cycle
When one cycle ends, you create the next feature as a new issue to start the next cycle. If you use a board, move that issue to In Progress when you start working on it.[7] Even without a board, the issue alone is enough.
Here is how you run the workflow you learned in Chapters 3–7 again with a single issue.
- Plan: Write what you want to change in an issue. If needed, add one line of acceptance criteria to SPEC.md (Chapter 3).
- Build: Get a plan in Plan Mode on a new branch, then build it (Chapter 4).
- Check: Run your verification checks and get proof. All existing checks must also pass (Chapter 5).
- Review: Write
fixes #numberin the PR and review it (Chapter 6). - Deploy: Merge it so it publishes to Pages again (Chapter 7).
You can also hand the issue directly to Claude Code.
Read GitHub issue #<issue-number>, add one line of acceptance criteria to SPEC.md, and start by making a plan. Don't edit any other files yet.If Claude says it cannot read the issue, copy the issue title and body and paste them into your prompt. That is the most reliable way.
Quick check
When running the next loop for a new issue, what must you check during the verification step?
Leave Releases for Later
A Release is a packaged version of your software that a wider audience can download and use.[8] It is important for programs that people download and install, but you don't really need it for a single-page web to-do board. Just know that it exists.
Try It Yourself
- On the main page of your
cafe-todo-boardrepository, click Issues → New issue to create a new issue.[9] Set the title to "Show overdue to-dos in red" and the label toenhancement. - Hand the issue details to Claude Code, add one line of acceptance criteria to SPEC.md, and get a plan first.
- Build it on a new branch, and get proof from your verification checks that both the new criteria and the existing criteria pass.
- Check the number next to the issue title, and write
fixes #issue-numberin the PR description. Review it, then merge it. - Check that the issue closed automatically and that the updated screen appears on Pages.
Up next: Chapter 9 covers how to keep secrets and personal information out of a public repository.
Summary
- An issue is a record for planning, discussing, and tracking work. Write down improvements and bugs as issues to start your next cycle.
- If you write
fixes #issue-numberin a PR, the issue closes automatically when you merge. Check the number on your screen. - Use labels (
bug,enhancement,documentation) and boards (Todo → In Progress → Done) once you have more issues. - The next cycle follows the same steps: Plan → Build → Check → Review → Deploy. Existing checks must continue to pass too.
Glossary
| Term | One-line meaning |
|---|---|
| Issue | A record for writing down and tracking tasks, bugs, and ideas |
| Label | A tag for sorting issues and PRs |
| Project | A table, board, and roadmap connected to your issues and PRs |
| Release | A packaged deployment unit that people can download and use |
Finished this chapter?
Progress is saved only in this browser. See your progress on the full table of contents.
Next chapter: Chapter 9. Safety and Responsibility
References (9)
GitHub official docs, "About issues". "You can create issues in your repository to plan, discuss, and track work." docs.github.com (checked on 2026-11-01) ↩︎
GitHub official docs, "About issues". "Mentioning an issue in another issue or pull request will create references between them and using keywords, like
fixes:, in your pull requests will automatically close the associated issues." docs.github.com (checked on 2026-11-01) ↩︎GitHub's beginner tutorial also creates its first issue this way during the planning stage. GitHub official docs, "Planning your work". "In the Add a title field, type
Display a list of starred repositories." docs.github.com (checked on 2026-11-01) ↩︎GitHub official docs, "Managing labels". "GitHub provides default labels in every new repository." / "
bug| Indicates an unexpected problem or unintended behavior" / "documentation| Indicates a need for improvements or additions to documentation" / "enhancement| Indicates new feature requests" docs.github.com (checked on 2026-11-01) ↩︎GitHub official docs, "About Projects". "A project is an adaptable table, board, and roadmap that integrates with your issues and pull requests on GitHub to help you plan and track your work effectively at the user or organization level." docs.github.com (checked on 2026-11-01) ↩︎
GitHub official docs, "Planning your work". "The board's columns represent stages of your work. As you make progress, move each item to show its status." docs.github.com (checked on 2026-11-01) ↩︎
GitHub official docs, "Reviewing your proposed changes". "If you have more features to build, create new issues and move them to In Progress when you start the next cycle." docs.github.com (checked on 2026-11-01) ↩︎
GitHub official docs, "About releases". "Releases are deployable software iterations you can package and make available for a wider audience to download and use." docs.github.com (checked on 2026-11-01) ↩︎
GitHub official docs, "Planning your work". "On the main page of your
stargazers-logrepository, click Issues." / "Click New issue." docs.github.com (checked on 2026-11-01) ↩︎