How to write reports with FarkiBot

An answer is something you read. A report is something you hand over.

FarkiBot’s Report task writes a document from your model and saves it as a Markdown file. It writes no model content, so it’s available to viewers as well as contributors, and there’s nothing to import afterwards.

Write a report

Open View > FarkiBot and switch the task dropdown to Report
Choose which document you want from the report dropdown
Set the Context chip to the packages the document should cover
Optionally type a brief
Press Enter

The four documents

Report	What it’s for
Model Overview	A narrative document for stakeholders who need to understand the estate without opening the model.
Gap & Risk Assessment	Prioritised findings, each with the named model content that evidences it, its impact, and a recommendation.
Reference Documentation	A systematic, complete walkthrough of every package — the one where the value is that nothing is missing.
Executive Summary	One page, business language, leading with the conclusion.

Pick by audience and purpose, not by size. An Executive Summary of a large estate and a Model Overview of a small one are different documents, not different lengths of the same one.

The brief is optional

The document kind and the scope are already a complete instruction — FarkiBot can write any of the four without a word from you.

Type a brief to steer it:

“Focus on the payments estate”
“Write for an incoming CTO”
“Emphasise anything that affects the Q3 migration”
“Assume the reader knows ArchiMate”

FarkiBot follows the brief within the shape of the document you chose.

Revise it like a colleague’s draft

A follow-up revises the document rather than starting over:

“Shorten the executive summary”
“Add a section on integration risk”
“Rewrite this for a board audience”
“Drop the appendix and expand section 3”

Each revision replaces the document, so Save .md always saves the current version.

Save the file

Save .md writes the file, named after the document’s own title — so a report called Farquind Application Estate: Gap & Risk Assessment saves under that name, not report-1.md.

The file is Markdown, which pastes cleanly into Confluence, Notion, Word, or a pull request.

Gaps are written in, not written around

Where the document needs something your model doesn’t record, FarkiBot says so in place rather than inventing it or quietly skipping the section.

In a Gap & Risk Assessment it goes further, and keeps two different problems apart:

Kind of gap	Example	The fix
A gap in the model	”No element records an owner.”	Add an Owner property and populate it.
A gap in the architecture	”These three systems have no owner.”	Assign owners.

Conflating those two is one of the most common ways an architecture document wastes its reader’s time. Keeping them separate is what makes the assessment actionable.

Web research works here too

Turn on Web before you write, and the document can compare your estate to current practice, check whether technologies are still supported, or cite what a standard requires now. Every web claim carries an inline citation.

An overview written purely from your model and one that compares it to the outside world are different documents, and both are useful. Decide which you want before you generate.

Reports and roles

Because a report only ever writes a file:

Viewers can run reports. They can’t generate or modify models, but they can produce documentation from what they can see.
Nothing is staged and nothing is imported — the output is a file, not a model change.