Documentation Jobs in DocsFab
A documentation job binds one named outcome to a repository revision and explicit authority in DocsFab. Its workflow defines the steps, and each step receives only its allowed tools and context.
This Task → Workflow → Step structure lets you inspect what the job was
asked to do, what it changed, and which evidence supports the result. Direct
live-agent conversation and edits use their own interactive-operation
evidence; they do not create a named-workflow run record. For the other
concepts behind a result, refer to Core Concepts.
The Model Proposes and the Runtime Controls
A model can propose a documentation change, but the model does not decide what can happen. The DocsFab runtime decides which job runs, what each step can read or change, when the job must stop, and what evidence it keeps.
The following table shows the layers that take part in one job.
Fixed workflows make the intended outcome, the authority, and the evidence reviewable. The runtime schedules only catalog-bound, hash-locked skills. A skill file on disk does not create or activate a job. For how the runtime binds inputs and connects to GitLab and the model, refer to DocsFab Architecture.
Catalog Jobs
The local docsfab CLI runs the jobs in its catalog. Run docsfab list to
see the jobs installed for you. The catalog contains the following jobs.
An unknown job name fails closed. For the ordered steps of each job, refer to Workflow Contracts in DocsFab.
What You Get Back
The model works in a disposable export of the pinned revision, not in your checkout. Your checkout stays unchanged. A finished job returns the following:
- A structured run record bound to the revision, workflow, and pinned inputs.
- Findings, when the job is a review or when write work cannot complete honestly.
- A Git patch, when a write-capable job produces a change.
Execution status and product readiness are separate results. A job can run
to completion and still report its outcome as not-ready, needs-input,
inconclusive, or blocked. An update that finds no documentation change is
needed reports a verified no-change result instead of a rewrite. For how
DocsFab reports a job that cannot finish, refer to
When a Job Stops in DocsFab.
A Result Grants No Authority
Evidence records what a job observed or produced. Authority is a separate, explicit decision that permits one narrowly defined change. A run record, a model response, or an artifact that a job wrote cannot grant authority by itself.
The following rules apply to every job:
- A green review is not a write.
- A patch is not merge authority.
- A model request for a write does not grant write authority.
- A draft merge request is a proposal, not an accepted change.
- A quality evaluation is evidence for reviewers, not approval to merge or publish.
Merge stays outside DocsFab, with one narrow exception. Your organization’s review, required checks, and an explicit merge decision remain separate from the job. Publication of the rendered documentation site is another separate step.
The exception is the product reference model’s own updates. With the
maintain-prm add-on on a Contribute grant, the feedback publisher readies its
own merge request and adds it to the merge train, and GitLab merges it after
the required pipeline passes. DocsFab never merges, approves, or readies any
other merge request. For the grant, refer to
Standing Repository Grant in the Glossary.
Delivering Results
After a successful create-documentation, update-documentation, or
restructure-documentation job, the CLI opens one draft merge request by
default. It uses glab with your own GitLab authentication, so you need an
origin remote (or --remote <name>), an authenticated glab, and permission
to push and create a merge request. Pass --patch-only to keep the patch
locally without opening a merge request.
DocsFab uses GitLab in two different ways. Keep them separate when you read a result. The following table compares them.
The model never receives a GitLab token or a general shell. Delivery checks the exact patch and target branch again immediately before it changes GitLab. A stale patch, a moved branch head, or missing permission stops delivery. To deliver a retained patch or recover a failed delivery, refer to Deliver or Recover a Draft Merge Request.
On a first write, DocsFab can propose a .docsfab.json project configuration
in the same patch. For the rules that limit which paths a job can write,
refer to The Write Scope.
Related Documentation
For more information, refer to the following pages: