Knowledge Work Plugins: give a work assistant a shared task file
Read productivity’s Markdown parser before trusting a round trip
Inspect section identifiers, checkbox parsing and save guards in dashboard.html, including cases that deserve a regression test.
What you will learn
- Section names become restricted identifiers
- The serializer preserves a particular schema
- Saving and watching are separate guards
Before you start
- Basic command-line and configuration reading
- Ability to work in a disposable authorized environment
Design an independent parser preview that exposes unsupported Markdown and conflicting headings before a dashboard save.
Key takeaways
- Heading normalization can merge or omit sections.
- Arbitrary Markdown is outside the task schema.
- Autosave guards do not establish conflict-free editing.
Section names become restricted identifiers
taskSectionId lowercases a heading and replaces runs outside ASCII letters and digits with hyphens. parseTaskMarkdown only creates tasks after a usable section identifier. A heading written solely with Chinese characters can therefore produce an empty identifier and fail to collect tasks underneath it.
Different headings can also normalize to the same identifier. The parser reuses the existing task array in that case. Keep the supplied English section labels during the first trial, then test any localized or customized headings on a copy.
The serializer preserves a particular schema
The parser recognizes second-level headings, task checkboxes, bold titles, notes and checkbox subtasks. toMarkdown rebuilds a document from those fields. Paragraphs or arbitrary embedded Markdown outside that representation are not guaranteed to survive a board save.
Task identifiers use time and randomness in the parsed representation. They should not be assumed to provide stable cross-device identity. An integration needing persistent identifiers should define and test its own format rather than infer one from transient card state.
Saving and watching are separate guards
markChanged schedules autoSave after 500 milliseconds. autoSave checks the file handle, pending changes and the saving flag before writing. checkForExternalChanges checks modification time, but returns while local changes are pending or a save is in progress.
These branches explain why a board can avoid interrupting an edit yet still need conflict handling for concurrent writers. Our conclusions come from source inspection; no browser race test was executed. The proposed fixture below is an acceptance plan, not a reported test result.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Inspect taskSectionId, parseTaskMarkdown and toMarkdown together.
- 2
Try ASCII, Chinese-only and colliding headings on disposable input.
- 3
Compare the complete original file with the serialized result.
Copy-ready example
{
"proposedCases": [
"Active",
"待办",
"A B / A-B",
"free paragraph before task"
],
"assertions": [
"section identity",
"task retention",
"round-trip diff"
],
"browserRaceTested": false
}Frequently asked questions
Can I localize every section heading safely?
Test first. The inspected identifier function keeps only ASCII letters and digits.
Does a successful save preserve every original line?
Not necessarily. The serializer rebuilds the supported task structure.
Sources
- Knowledge Work Plugins / productivity/skills/dashboard.htmlSource checked 2026-09-18
- Knowledge Work Plugins / productivity/skills/task-management/SKILL.mdSource checked 2026-09-18