Best Practices

qmims works best when you treat README generation as an iterative workflow rather than a one-click final step. Use Kiro-backed generation to create a strong draft, then refine structure, instructions, and examples until the documentation matches the real behavior of your project.

Build a Strong README Structure

A useful README usually answers these questions quickly:

Choose the Right qmims Workflow

qmims generate --mode auto

qmims generate --mode template:detailed

qmims edit

Write Better Embedded Instructions

Kiro can only be as specific as the instruction you provide. The more grounded your instruction is in your project context and desired format, the better the output tends to be.

<!-- qmims: Write about installation -->

<!-- qmims: Provide step-by-step installation instructions using the detected package manager, including prerequisites and a verification command. -->

<!-- qmims: List the features -->

<!-- qmims: List the main user-facing features of this CLI tool based on the commands, options, and workflows implemented in the src directory. -->

<!-- qmims: Document the API -->

<!-- qmims: Document the exported API as a table with columns for name, purpose, parameters, and return value. -->

Review AI-Generated Output Carefully

qmims helps you move faster, but you should still review the generated content before treating it as final documentation.

• Check installation commands against the actual package manager and runtime
• Verify code examples still match the current API
• Remove claims that are too broad or speculative
• Make sure feature lists reflect real implemented behavior
• Confirm links, filenames, and command names are correct

Use Dry Runs and Verbose Output

Before changing important documentation, preview the workflow and use diagnostic output when you need more visibility.

qmims generate --dry-run
qmims edit --dry-run
qmims generate --verbose

• Use --dry-run to confirm the planned action and target file
• Use --verbose when debugging auth, file resolution, or generation behavior
• Prefer previewing before overwriting existing docs

Keep Kiro Ready

Since qmims depends on Kiro CLI, a good documentation workflow also means keeping your Kiro setup healthy.

kiro-cli whoami
kiro-cli login
kiro-cli doctor

For automation or CI, prefer a headless setup using KIRO_API_KEY rather than relying on an interactive login session.

Prefer Explicit Git Workflows

qmims does not currently expose Git auto-commit as a supported feature. If you want generated documentation committed, do it explicitly in your normal workflow.

qmims generate
git add README.md
git commit -m "docs: update README"

This keeps generated documentation changes visible and reviewable instead of hiding them behind an automatic commit step.

Suggested Documentation Workflow

1. Generate a first draft

   qmims generate --dry-run
   qmims generate

2. Improve structure if needed

   qmims generate --mode template:detailed

3. Add targeted embedded instructions

   <!-- qmims: Update this section based on the latest CLI behavior. -->

4. Process those instructions

   qmims edit

5. Review and commit the result

Related Docs

• Generation Modes
• Embedded Instructions
• Advanced Usage
• Troubleshooting