One board for the book: every issue a file, a Kanban page built from the files, and every content issue pinned to a version and a sentence

In short

• I need one view of the work. What is open, blocked and done, across the roles, and what waits on me.
• The pieces exist. Each role keeps issues as files in open, blocked and done; the folder is the status; ten issues today.
• The view across them is written by hand. The vault's board is rewritten whenever an issue moves, so it will drift.
• A second kind of issue has nowhere to live. The content issue: a finding about a sentence of the book, which needs the version, the quote and an answer.
• Work issues stay with the roles, here; content issues live in the vault. Next to the working copy of the text; same three statuses, fixed fields.
• Every board is generated. The site's from the work issues, the vault's from the content issues; never edited by hand.
• The 2018 GitHub issues come in as content issues. 43 of them, 35 still open, each with its number and link.

What we have

The issues guide this site started with is short, and it is right: each role owns team/<role>/issues/open|blocked|done/, the folder is the status, a status change is a git mv, a file is NNN__slug.md and is never renumbered, and only the owning role writes into its folder. There is no tool, and that is a feature: an agent in any session can read and move a file.

Today there are ten issues:

The view across them is board/BOARD.md in the vault: a markdown list of the ten, plus seven questions for me. Its own first line says it is "rewritten by whoever moves an issue". That will work for ten issues and one session. It will not work for a hundred issues and four sessions, because the one thing a hand-written index is guaranteed to do is fall behind the files it indexes.

Two kinds of issue

Most of what will happen to this book is not a task. It is a question about the text.

• A work issue is a task for a role: build the PDF, run the first interview, check the map. It has a "what", a "done when", where it came from, and, when blocked, what it waits on. It belongs to one role and lives in that role's folder. This is what exists.
• A content issue is a finding about the book: a spelling mistake in a chapter, a 2018 claim that dated, a broken link, a reader saying a chapter lost them, a 2018 GitHub issue asking for a chapter on coordinated disclosure, or me saying a paragraph is wrong. It belongs to the book, not to a role. It needs the file, the version read, the sentence quoted, the kind, who raised it, and in the end an answer.

The reviewer's role already describes content issues without naming them: findings, numbered, each with its evidence and severity, and an answer recorded next to it, "fixed (where), declined (why), or deferred (to which version)". The proposal is to give them a home that every role and the board can see, rather than leaving them inside review records.

Where content issues live

In the vault, at board/issues/open|blocked|done/, with the same rules as the roles' folders: the folder is the status, NNN__slug.md, never renumbered, never deleted.

That is where the working text is, and a finding belongs next to the sentence it is about. When a version is signed off and comes into this repository, the content issues it answered come with it in its record, so what we found and decided about an official version is official too. The working copy starts from the book as site v0.2.0 froze it: v1.0.0, the published book.

Who writes: any role may create a content issue, and records itself as the one who raised it. Only the editor moves one to done, because only the editor changes the text; a content issue is done when its answer is recorded, whether that answer is "fixed in v1.0.1" or "declined, because the book is not doing that". A content issue waiting on my decision is blocked, with Waits on. Dinis. Writing into the vault needs its write key, which I hold and give to the role that needs it.

The fields, in the same style as the work issues:

# <the finding, as a sentence>

**File.** <path in the working copy>
**Version.** book v1.0.0
**Quote.** "<the sentence, word for word>"
**Kind.** spelling | dated | wrong | missing | broken link | structure | reader | idea
**Raised by.** reviewer | editor | publisher | journalist | Dinis | reader (source) | 2018 GitHub issue #N
**For.** the book version this should land in, or "undecided"
**Answer.** fixed (where, which version) | declined (why) | deferred (to which version)

The Quote is checked: a script finds the quoted sentence in the named file at the named version, and refuses the issue if it is not there, which is the newsroom's rule that a quote is word for word, applied to findings.

The boards

Two generated views, one per place the issues live.

On this site, board/index.html, built from every role's work issues:

• Three columns, open, blocked and done, because those are the statuses the folders have. No "in progress" column: a role that is working on an issue says so in its debrief, and a fourth folder would be a fourth thing to keep in step.
• A card per issue: the title, the role, and for a blocked card, what it waits on.
• Filters by role.
• A "waits on Dinis" strip at the top: every blocked issue whose Waits on. names me. This is the part I will read every day.
• Counts per column and per role, which the roles' debriefs can quote.

In the vault, board/BOARD.md, generated from the content issues by a script kept in this repository and run against a checkout of the vault before each push: the same three columns, a card per content issue with its kind, its file and the version it is for, filters by kind and target version, and the same "waits on Dinis" strip. It replaces the hand-written board.

The 2018 GitHub issues

The first edition took feedback through GitHub issues, and showed some of them in the book: the 2018 Leanpub build has a page listing the issues labelled show-in-book. Site v0.2.0 captured the whole of the 2018 repository's issues, pull requests and comments under admin/content/github/, for the contributors page. Counted from that capture:

And 24 pull requests, 21 of them merged. The eight closed issues are a typo on the cover and seven notes from one reader on the chaos engineering chapter; the 35 open ones run from 22 February 2018 to 3 October 2019, and most are ideas for chapters: coordinated disclosure, closure, typography and design, cloud-native, the C4 model, "understand what game is being played", summits versus conferences, HTTP from the basics, "is this book just for Gen Z".

Each comes in as a content issue in the vault, raised by "2018 GitHub issue #N", with its link, its date, its labels and its author, so the people who asked are credited if the book does what they asked. The 35 open ones go in open/; the 8 closed ones go straight to done/, with the answer the 2018 repository records. Issue 3 deserves attention of its own: it says fixes were made in the Leanpub build repository and never brought back to the source, which means the published text and the frozen source may differ in places, and the previous article asks the publisher to check.

The gate

What the checks should refuse, so the boards stay honest. In this repository, validate.js:

• A work issue without What., Done when. and From.; a blocked one without Waits on.
• A number used twice in the same folder.
• A status written inside a file, since the folder is the status.

In the vault, the board script:

• A content issue without File., Version., Quote. and Kind., or a quote that is not in the file at that version.
• A content issue in done/ without an Answer.
• The same numbering and status rules.

The brief

For the editor, with the other roles reading along. Read team/editor/role.md and team/ISSUES.md first.

1. Create board/issues/open|blocked|done/ in the vault, with the write key I give you, and add the content issue format to team/ISSUES.md. Done when the guide describes both kinds and an example content issue is in the vault.
2. Teach the build to write the site's board: board/index.html from every role's work issues, with the three columns, the filter, the counts and the "waits on Dinis" strip. Done when moving an issue with git mv and rebuilding moves its card, with nothing else edited.
3. Write the vault board script: in admin/build/, run against a vault checkout, it writes board/BOARD.md from the content issues and refuses one with a missing field or a quote not in its file. Done when the vault's board is its output, and each check has a failing example.
4. Teach the gate the work-issue checks above. Done when each has a failing example that it refuses.
5. Bring in the 43 GitHub issues of the 2018 repository from admin/content/github/ as content issues in the vault, generated rather than typed, open ones in open/ and closed ones in done/. Done when every issue has a file, and the vault board's count matches the capture's.
6. Move the seven open questions from the vault's board into blocked issues that wait on me, each in the role that needs the answer. Done when the "waits on Dinis" strip shows them and the hand-written board is gone.
7. Add the site's board to the navigation and to llms.txt.

Decided: content issues live in the vault (decision 005). Still a question for me: only the editor closes a content issue, agreed?

What this does not claim

• Nothing here is built. The board is a proposal; the editor builds it.
• The GitHub counts are from a capture. admin/content/github/ as site v0.2.0 took it on 18 October 2026; an issue opened since is not in it.
• No "in progress" column is a choice. If the roles find they need one, it is a fourth folder and a change to the guide.
• The vault's board needs a script and a key. It cannot be built by the site's release pipeline, which does not hold the vault's write key.
• A Kanban page is a view, not a tool. There is no drag and drop; a card moves when its file moves.

If you keep a board like this for your own writing, or have opinions on what it should show, write to agent@riskmandate.ai.

Where this comes from

Two voice memos of mine on 18 October 2026, written up by this site's journalist, gen-z.journalist, in my voice; the second decided that content issues live in the vault (decision 005). The argument and the editorial responsibility are mine.

The record: team/ISSUES.md and the ten issue files under team/*/issues/ in this repository at site v0.2.0, counted by folder; board/BOARD.md in the public vault c14khrb8, cloned read-only on 18 October 2026, quoted from its first line; team/reviewer/role.md for the finding format and its answers. The 2018 issues are counted from admin/content/github/issues-p1.json and pulls.json, captured by site v0.2.0, by state and label, with pull requests left out of the issue count; the show-in-book page is manuscript/github-issues.md in DinisCruz/Book_Generation_Z_Developer_Build, 8 October 2018. The pattern is graphs.sgit.ai's Issues-FS-lite, as team/ISSUES.md describes it.