Postmortem: Docmgr Usability and Documentation Gaps (PI-LAUNCHER-001)

03-postmortem-docmgr-usability-and-documentation-gaps.md

title	Postmortem: Docmgr Usability and Documentation Gaps
doc-type	reference
ticket	PI-LAUNCHER-001
topics	docmgr documentation usability tooling

Postmortem: Docmgr Usability and Documentation Gaps

Goal

Document every friction point, confusion, and workaround encountered while using docmgr for ticket-based research during the PI-LAUNCHER-001 project. The intent is to provide actionable feedback for improving docmgr's documentation, CLI ergonomics, and validation behavior.

Context

This postmortem was written immediately after completing a full ticket-research-docmgr-remarkable workflow:

1. Created ticket PI-LAUNCHER-001
2. Added 4 documents (design-doc, logbook, diary, postmortem)
3. Downloaded ~10 external source files into sources/
4. Ran docmgr doctor multiple times
5. Committed changes and uploaded to reMarkable

The user is an experienced developer but new to docmgr. The workflow was guided by the ticket-research-docmgr-remarkable and diary skills.

---

Issues Encountered

Issue 1: No Clear Guidance on When .docmgrignore Works vs. When Frontmatter is Required

What happened: We downloaded external source files (README.md, source code, JSON) into sources/. These files were third-party artifacts, not documents we authored. We created a .docmgrignore file in sources/ with content * to exclude them from docmgr's view.

What went wrong: docmgr doctor still scanned the sources/ directory and reported errors:

• invalid_frontmatter — "frontmatter delimiters '---' not found"
• missing_numeric_prefix — "file without numeric prefix"

Why this was confusing: The .docmgrignore file apparently does not exclude files from validation. Or perhaps .docmgrignore is not recursive, or requires a different format. The skill documentation and docmgr help do not clearly explain:

• Whether .docmgrignore affects doctor, validate, or only search
• The syntax of .docmgrignore (gitignore-style? glob? exact paths?)
• Whether .docmgrignore in a subdirectory is respected

Workaround: Added YAML frontmatter to the downloaded source files:

---
title: "OpenClaw Pi Integration"
doc-type: reference
---

This is semantically wrong — these are not docmgr documents, they are third-party source artifacts. But it was the only way to silence doctor.

Suggested fix:

1. Document .docmgrignore behavior clearly: what it affects, what syntax it uses, whether it is recursive
2. Consider a docmgr doctor --ignore-sources flag or a per-directory .docmgrignore that actually suppresses validation
3. Or provide a docmgr doctor --skip-dir <dir> option for directories like sources/, scripts/, archive/

---

Issue 2: Frontmatter is Required but Not Auto-Generated

What happened: We wrote three substantial documents (design doc, research logbook, diary) totaling ~2,500 lines. None of them had frontmatter initially. When we ran docmgr doc relate, it failed with:

Error: document has invalid frontmatter (fix before relating files):
  ... frontmatter delimiters '---' not found

Why this was frustrating:

• The error only appeared when running doc relate, not when writing the files
• We had already written 2,500 lines before discovering this requirement
• The skill says "Write the primary analysis document" but does not remind you to add frontmatter first
• The doc add command creates files with frontmatter, but we wrote files directly with write tool

Workaround: Added frontmatter manually to all three documents:

---
title: "..."
doc-type: design-doc
ticket: PI-LAUNCHER-001
topics:
  - pi-agent
  - launcher
  - declarative-config
---

Suggested fix:

1. Auto-prepend frontmatter when docmgr doc add is used (already works)
2. Provide docmgr doc fix-frontmatter <file> to auto-add minimal frontmatter
3. Make doc relate warn but not fail on missing frontmatter, or auto-add it
4. Update the ticket-research-docmgr-remarkable skill to include a frontmatter check in the workflow

---

Issue 3: Vocabulary Errors Are Cryptic and the Fix is Scattered

What happened: First docmgr doctor run produced:

[warning] Unknown vocabulary value for Topics
File: .../index.md
Field: Topics
Value: "declarative-config,glazed,launcher,pi-agent,yaml"
Known values: chat, backend, websocket

Why this was confusing:

• The error message says "add to vocabulary" but does not tell you the exact command
• The suggested command in the error is docmgr vocab add --category topics --slug declarative-config,glazed,launcher,pi-agent,yaml — but this is wrong! It would create a single slug with commas, not five separate slugs
• We had to run docmgr vocab add five separate times
• The skill says "If vocabulary warnings appear, add it to the vocabulary" but does not explain that you need one command per slug

Workaround: Ran five separate commands:

docmgr vocab add --category topics --slug pi-agent --description "Pi coding agent"
docmgr vocab add --category topics --slug launcher --description "CLI launcher tools"
# ... etc

Suggested fix:

1. Make docmgr vocab add accept multiple --slug arguments in one command
2. Provide docmgr vocab add-batch --category topics --slugs "a,b,c" --descriptions "d1,d2,d3"
3. Or auto-suggest the correct commands in the doctor output, not the incorrect comma-separated version
4. Consider auto-adding unknown topics with a placeholder description, then prompting the user to refine

---

Issue 4: doc relate Fails Opaquely When Frontmatter is Missing

What happened: After writing the design doc, we ran:

docmgr doc relate --doc ttmp/.../design-doc/01-...md --file-note "/abs/path:reason"

It failed with:

Error: document has invalid frontmatter (fix before relating files)

Why this was frustrating:

• The error does not say which file has invalid frontmatter. We had to guess it was the target document, not the related file
• The error message is "fix before relating files" but we were trying to relate files to the document
• There is no --force or --skip-validation flag to bypass this

Suggested fix:

1. Make the error message explicit: "Document X has invalid frontmatter. Run docmgr validate frontmatter --doc X for details."
2. Add --skip-frontmatter-check to doc relate for power users
3. Provide docmgr validate frontmatter --fix to auto-add minimal frontmatter

---

Issue 5: No Way to See a Document's Current Relations Without Opening the File

What happened: We wanted to verify that doc relate commands had worked. We had to open the markdown file and scroll to the bottom to see the ## RelatedFiles section.

Why this was frustrating:

• docmgr doc list --ticket X shows documents but not their relations
• docmgr doc show <doc> does not exist
• The only way to audit relations is to cat the file or grep for RelatedFiles

Suggested fix:

1. Add docmgr doc show <doc> that prints frontmatter + related files + changelog entries
2. Add docmgr doc list --ticket X --with-relations
3. Or add docmgr relate list --doc <doc>

---

Issue 6: Skill Documentation is Good but the Workflow is Implicit

What happened: The ticket-research-docmgr-remarkable skill provides excellent structure for the output but does not provide a clear step-by-step checklist for the process.

For example, we did not know:

• Whether to write files first or create docs first
• When to run doctor (after every doc? at the end?)
• That .docmgrignore might not work as expected
• That vocabulary needs to be populated before doctor passes

Suggested fix:

1. Add an explicit "Step-by-step workflow" section to the skill with numbered steps
2. Include a pre-flight checklist: frontmatter, vocabulary, .docmgrignore behavior
3. Provide a template command sequence that can be copy-pasted:

# 1. Create ticket
docmgr ticket create-ticket ...

# 2. Add docs (with frontmatter auto-generated)
docmgr doc add --ticket X --doc-type design-doc --title "..."

# 3. Write content (frontmatter already present)

# 4. Add vocabulary (if using custom topics)
docmgr vocab add --category topics --slug my-topic --description "..."

# 5. Validate
docmgr doctor --ticket X --stale-after 30

# 6. Relate files
docmgr doc relate --doc ... --file-note "path:reason"

# 7. Upload
docmgr upload ...

---

Issue 7: Changelog and Task Updates Feel Redundant with Git Commits

What happened: We wrote code, committed, then had to separately update docmgr changelog and docmgr task check. The same information (what changed, why, commit hash) is recorded in two places.

Why this was frustrating:

• Triple bookkeeping: git commit message, docmgr changelog entry, docmgr task check
• Easy to forget one of them
• The changelog entry format is verbose for simple changes

Suggested fix:

1. Provide docmgr changelog update-from-git --ticket X that auto-generates entries from recent commits
2. Or docmgr task check-from-git --ticket X that marks tasks as done based on commit messages
3. Or a docmgr sync command that compares git history with docmgr state and suggests updates

---

Positive Findings

Despite the issues above, docmgr worked well for:

1. Ticket organization: The ttmp/YYYY/MM/DD/TICKET-.../ structure is excellent
2. Document types: design-doc, reference, playbook categories are intuitive
3. Frontmatter validation: Once present, it keeps metadata consistent
4. Doctor: Catches real problems (missing frontmatter, unknown topics)
5. reMarkable integration: Uploading a bundle with --toc-depth 2 produced a clean PDF

Recommendations Summary

Priority	Recommendation	Effort
High	Clarify .docmgrignore behavior in docs	Low
High	Auto-suggest correct vocab commands in doctor output	Low
High	Add explicit step-by-step workflow to skill	Low
Medium	docmgr doc fix-frontmatter command	Medium
Medium	docmgr doc show command	Low
Medium	doc relate --skip-frontmatter-check flag	Low
Medium	docmgr changelog update-from-git	Medium
Low	Batch vocab add: --slugs a,b,c	Low
Low	docmgr doctor --skip-dir <dir>	Low