QDG Knowledge Base project documentation rules

These instructions apply when starting or continuing a project from this template. They supplement the local documentation, changelog, handover and version-control templates.

Canonical name

Use QDG Knowledge Base or QDG KB for the shared documentation product. qdb.qdatasite.com is the public hostname. Do not call the product “QDB KB”, “QDB KB Wiki”, “QDG Wiki” or “KB Wiki” except when explaining a legacy name.

Ask once at project setup

This is a mandatory setup interview, not background guidance. Before implementing or creating the project structure, inspect the project for documents/PROJECT_SETUP.md and a recorded QDG KB decision. If either decision is missing, show the applicable question to Robert and wait for the answer. Use the client's structured question controls when available; otherwise show the choices as a plain Markdown checklist. Do not silently infer an answer from the repository.

Ask this first:

Should this project be documented in QDG Knowledge Base? Y/N

After Robert answers the documentation question, ask:

What language or framework will this project use? Select all that apply.

- [ ] Python
- [ ] .NET
- [ ] Django
- [ ] Other — enter the language/framework:

Offer a likely selection as an editable recommendation when existing evidence makes it clear, but still ask for confirmation. Django may be selected together with Python. If Other is selected, record the supplied language or framework rather than the word “Other”.

Record the technology answer in documents/PROJECT_SETUP.md:

<h1>Project setup</h1>

- Project name: [current project name]
- Primary language/framework: [selected values]
- Setup date: YYYY-MM-DD
- Confirmed by: Robert

If the project has no documents directory yet, create it as part of the standard structure before writing this record. Do not repeatedly ask either setup question after its answer has been recorded, unless Robert asks to change the project setup.

If the answer is No

Create or update documents/QDG_KB.md in the project with:

<h1>QDG Knowledge Base status</h1>

- Document this project in QDG KB: No
- Decision date: YYYY-MM-DD
- Decision made by: Robert

Do not publish this project to QDG KB unless Robert changes this decision.

If the project does not use a documents directory, put QDG_KB.md in the project root. Do not create a QDG KB project or pages. Continue maintaining any local documentation required by the project templates.

If the answer is Yes

Ask for the shared Knowledge Base project name. Offer the current local project name as the editable default. This question follows the documentation and technology questions:

QDG Knowledge Base project name: [current project name]

Then show this Markdown checklist and ask Robert to select the initial pages:

Which pages should be created initially? We can add more pages later.

- [ ] Project Description
- [ ] Change Log
- [ ] User Guide
- [ ] How to Use
- [ ] Other — enter page title(s):

Do not interpret an unticked box as selected. If Other is selected, ask for each page title and its purpose. Ask only for missing information; keep the setup interaction short.

Record the result in documents/QDG_KB.md, or in the project root if there is no documents directory. Include:

• Document this project in QDG KB: Yes;
• the exact QDG KB project display name;
• the QDG KB project slug or identifier after it is known;
• the selected initial pages and their page slugs/identifiers after creation;
• the decision date and decision maker;
• any additional documentation triggers specific to the project.

Before creating anything, search or list QDG KB projects and confirm that the intended project does not already exist under the name, slug, repository path or an obvious variant. Reuse the canonical existing project when it is the same project. Never create a duplicate merely because punctuation, spacing or capitalisation differs.

Initial page purpose

Use the selected pages as follows:

• Project Description — purpose, business context, scope, users, architecture, dependencies, important data flows, ownership, current status and major constraints.
• Change Log — dated, version-aware record of meaningful changes, fixes, releases, deployment changes, migrations, documentation changes and known follow-up work.
• User Guide — audience-focused explanation of features, workflows, expected results, limitations and troubleshooting.
• How to Use — concise prerequisites, configuration, commands or UI steps, examples and verification instructions needed to operate the project.
• Other — a clearly titled page for material that does not fit the standard set, such as an API reference, deployment runbook, data dictionary, recovery procedure or design decision record.

Do not create empty placeholder pages. Draft each selected page from verified project evidence. If there is not enough information, record the missing information locally and ask Robert before publishing assumptions as facts.

Required update triggers

If QDG KB documentation is enabled for the project, treat documentation as part of completing the work at the defined checkpoints rather than as optional follow-up. Do not ask after every user request whether documentation, a changelog or a handover should be updated. Routine questions, investigations, small edits and intermediate iterations require neither a prompt nor an update.

Update the QDG KB documentation set after significant work, when Robert explicitly requests a handover, or as part of a meaningful push/delivery. Update the Change Log at those checkpoints. Create or refresh the handover at the same checkpoint when the work materially changes the state a future agent needs to resume. One consolidated entry may cover one logical delivery containing several related commits; do not create noisy entries for temporary commits, formatting-only churn or repeated push attempts. Include, when applicable:

• date and project/application version;
• concise description of what changed and why;
• important files, components or behaviour affected;
• tests or verification performed and their results;
• deployment or operational effect;
• source commit, branch, release or pull-request reference after it is known;
• risks, compatibility notes, rollback information and remaining work.

For a commit-and-push workflow, prepare the documentation with the change, create the commit, then publish or amend the QDG KB changelog entry with the final commit identifier before reporting the delivery complete. Do not claim a push, deployment or test succeeded until it actually did.

At handover, make the QDG KB changelog and relevant operational pages match the handed-over state. Record unfinished work and blockers explicitly.

Significant-work review

After a significant change, review all selected pages, not only the changelog. Significant work includes a new capability, changed user workflow, architectural or data-flow change, interface or configuration change, deployment change, dependency or security change, material bug fix, renamed concept, new operational requirement, or changed limitation.

Update only the pages affected:

• revise Project Description when purpose, scope, architecture, dependencies, ownership, terminology or status changes;
• revise User Guide when user-visible behaviour, features, limitations or troubleshooting changes;
• revise How to Use when prerequisites, setup, configuration, commands, UI steps, examples or verification changes;
• revise an Other page when its specialist subject changes.

Avoid copying the same long explanation into several pages. Put detailed material in the most appropriate page and link or briefly cross-reference it from the others.

Reusable know-how and Markdown review

When work creates or materially improves a .md file containing reusable know-how, a detailed technical explanation, a runbook, recovery steps, configuration guidance, an investigation outcome, or an important design decision, ask:

This work produced reusable documentation in [file]. Should it be included in QDG Knowledge Base?
If yes, should it update an existing page or become a new page?

Do not ask for routine generated notes, temporary plans or content already covered by a selected page. If Robert has already instructed that the material belongs in QDG KB, publish it without asking the same question again.

Do not paste a local Markdown file blindly. Reconcile it with the current QDG KB page, remove local- only or sensitive material, and edit it into a durable team document.

Safe publishing workflow

When QDG KB MCP tools are available:

1. Read the current QDG KB project and target page before writing.
2. Validate the proposed Markdown when a validation tool is available.
3. Preserve accurate existing content and merge the new information.
4. Update using the exact current page version so concurrent changes cannot be overwritten.
5. If a version conflict occurs, reread, merge and retry. Never force or blindly overwrite.
6. Read the resulting page back and verify its version/content before reporting success.

Never publish secrets, bearer tokens, passwords, private credential paths, personal data, raw production data or unreviewed sensitive operational inventory. Use placeholders and safe references.

If QDG KB is unavailable, do not pretend the update succeeded and do not block a necessary local commit solely because the documentation service is temporarily unavailable. Record the exact pending QDG KB update in documents/QDG_KB.md and the handover, tell Robert, and complete it when access is restored. Clear the pending note only after the published page has been verified.

Completion check

Before reporting a significant change, requested handover, or meaningful push/delivery complete, confirm:

• the recorded QDG KB Yes/No decision was followed;
• the Change Log was updated when the delivery was meaningful;
• significant work triggered a review of Project Description, User Guide, How to Use and selected specialist pages;
• reusable Markdown know-how was either published, declined by Robert or recorded as pending;
• no secrets or sensitive data were published;
• every reported QDG KB write was read back and verified.