Risk-First: the site behind a risk-led way of reading software practice

The argument that risk is the common denominator

The site opens by noting that software development is crowded with different practices, metrics, methodologies, tools and techniques, and then asks what unites them all. Metrics such as number of open tickets, code coverage or release cadence give a numerical feel for how things are going, while methodologies such as Scrum, Waterfall and Lean give different approaches to organising. The Risk-First perspective is that all of these have at their heart the job of managing different risks.

The examples given make the point concrete. A story about improving the user login screen reduces the risk of users not signing up. Writing unit tests tackles the risk of bugs going to production, and also defends against the risk of future changes breaking existing functionality. A task about improving health indicators addresses the risk of the application failing and no-one reacting to it. Implementing a new function fixes the risk that users are dissatisfied and go elsewhere.

The framing is that risk is not something that just appears in a report, it actually drives everything we do. That is a stronger claim than saying risk is one input among several, and it is the reason the site keeps a single word as its organising idea.

What the repository actually contains

This is a website repository, and the layout says so. The content lives under src/ and _drafts/, the Docusaurus configuration is docusaurus.config.js with sidebars.js beside it, and there are directories for docs/, numbers/, static/, scripts/, unused_content/ and used_content/, plus a babel.config.js.

Several files are more interesting than a typical docs site has. There is a dictionary.txt, an errors.txt, a generated-files.txt, a used-files.txt and a used-files2.txt, which suggests the author tracks vocabulary and file-level bookkeeping by hand. There is also a .kite9 directory, a hosted issue tracker, and a CONTRIBUTING.md, so community workflow lives in tooling around the repository rather than in a large set of templates.

The numbers/ directory and the Chart.js plus react-chartjs-2 dependencies point to the site rendering charts, and rehype-katex with remark-math means it renders mathematical notation. xml2js and @mdx-js/react are present for MDX content, and the classic preset with the Algolia search theme means the site ships with a search box.

The project name in package.json is rf-website and the version field is 0.0.0, which is the convention for a private package that is never published.

The build pipeline runs a podcast generator and a frontmatter check

The scripts section of package.json is the clearest view of how the site is produced. Two custom Node scripts sit on top of the Docusaurus commands:

"generate-podcast": "node scripts/generatePodcastData.js",
"check-frontmatter": "node scripts/check-frontmatter.js",
"prestart": "npm run generate-podcast",
"prebuild": "npm run generate-podcast && npm run check-frontmatter",
"start": "npm run prestart && docusaurus start",
"build": "npm run prebuild && docusaurus build",
"deploy": "docusaurus deploy"

The prebuild hook is the interesting part. A production build first regenerates the podcast data and then validates frontmatter, and only then does docusaurus build run. That means content with malformed frontmatter fails the build rather than publishing badly, and the podcast listing is never stale in a deployed build.

The prestart hook regenerates the podcast data for local development, so a preview run and a production run agree on that content. The remaining scripts are stock Docusaurus passthroughs for swizzling, deploying, clearing the cache, serving a built site, and writing translations or heading ids.

The engine requirement is node >=18.0, and there is a browserslist for both production and development targets.

The book is separate from the site, and the licensing differs

The site is the writing, and the book is a separate artefact. The second edition of the Risk-First book is being published by the Pragmatic Bookshelf, and at the time of writing it is available for free, with details on a page at riskfirst.org/Risk-First-Second-Edition.

That distinction matters for licensing, and the two are not the same. The repository itself is licensed CC-BY-4.0, which is a content licence rather than a software licence, appropriate for a site that is mostly prose. The Creative Commons Attribution 4.0 terms let others reuse the writing with attribution. The book, by contrast, is a commercial publication from a publisher, so a reprint or a redistribution of the book is a different question from copying a chapter draft from the site, and the repository does not settle it.

The README also points to a Chinese translation, README_CN.md, and a Japanese one, README_JA.md, which tells you the site itself is treated as a multilingual project rather than a single-language blog.

Why a risk model is not a metric dashboard

It is worth being explicit about what this project is not, because the name invites the wrong comparison. There is no metric computed here, no dashboard, and nothing in the repository inspects a codebase. The dependency list contains no parser, no analyzer and no CI reporter. The deliverable is a body of ideas and a way of reasoning about them.

The alternative framing, and the one this project argues against, is the metrics-first view: pick measures such as open ticket count, coverage or release cadence, and treat the numbers as the definition of how healthy the work is. Risk-First keeps the numbers but changes what they are for. A coverage figure is a proxy for the risk of future changes breaking existing behaviour, and a release cadence is a proxy for the risk of a long unreleased branch diverging. Once the measure is a proxy for a risk, the team can argue about the risk itself, including whether that risk is one worth spending effort on at all.

That is why the site lists Scrum, Waterfall and Lean side by side as methodologies rather than promoting one. The claim is that they differ in which risks they foreground, not that one of them is correct.

A working setup for a local preview

Nothing in the repository documentation is a build guide, so the setup follows from the package.json scripts. The project uses npm, with a package-lock.json present, and it is private, so you clone rather than install it as a dependency.

With Node 18 or newer in place, the local preview path is the start script, which runs the podcast generator first and then hands over to the Docusaurus development server, and the production path is the build script, which adds the frontmatter validation step. Both are plain npm script names, so you invoke them as npm start and npm run build.

The result is a static site that can be served locally with the serve script, or published with the deploy script. The site is a static Docusaurus build, so hosting is whatever static host the deployment target points at, and the Algolia search theme means that a search index has to be configured separately for the search box to return anything.

Contributing content means adding Markdown or MDX under src/ or _drafts/ and making sure the frontmatter passes the check that runs on every build, since a failure there blocks the build rather than warning in the preview.

Editorial conclusion

Adopt this repository if you want to publish long-form writing on software risk under an open licence, and you are comfortable working inside Docusaurus conventions, because the repository is the site and the book rather than a library or a service. Do not adopt it if you want a tool that measures risk in your own codebase, since nothing here instruments a project, and be careful with the second edition licensing if you plan to reprint it, since the site content is CC-BY-4.0 while the book is published by Pragmatic Bookshelf. Before your first pull request, run npm run check-frontmatter, because the build refuses to proceed without it, and read CONTRIBUTING.md and the .kite9 directory, which indicate that issues and drafts are tracked outside the code itself.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. Project website
4. README
5. risk-first/website on GitHub