description-frontmatter-authoring

Description Frontmatter Authoring

Use this skill to make frontmatter descriptions work as the repository's routing layer.

docgarden match is metadata-first discovery, not full-text search. It scores name, path context, and frontmatter description; it does not rely on the document body for normal routing. A good description tells an agent what the document is for and when to read it.

Workflow

1. Identify the routing job.

   • Write down 2-5 realistic queries that should find the document.
   • Write down nearby documents that should not outrank it.

2. Inspect the current route.

   • Run docgarden match <query> for each realistic query.
   • Use docgarden match --explain <query> when ranking looks surprising.

3. Rewrite the description as a positive routing cue.

   • Lead with the document type or task family.
   • Include action words an agent or user would actually ask for.
   • Include the scope only when it helps separate this document from similar ones.
   • Keep it one sentence unless the document truly has multiple routing jobs.

4. Remove accidental attractors.

   • Avoid saying what the document is not. Negated phrases still add matchable tokens.
   • Avoid broad words that make the document appear for unrelated workflows.
   • Avoid duplicating another document's strongest trigger phrase unless both should route together.

5. Validate the route and the lint policy.

   • Rerun the same docgarden match <query> checks.
   • After modifying any Markdown file, run docgarden lint <changed-files> --color never.

Description Pattern

Use this shape:

<Document kind> for <specific task/scope>; read when <agent intent, workflow, or decision point>.

Examples:

description: "Working design draft for `docgarden match` scoring, including the shipped BM25F model, stopword handling, and future tuning directions."

description: "Create, update, revise, reopen, or rescope an ExecPlan using `docs/PLANS.md`; use when shaping plan requirements before implementation."

description: "Follow-up tasks and cleanup items; read when looking for deferred implementation work, small backlog items, or candidate topics to promote into a future plan."

Negative-Phrase Trap

Do not encode exclusions in the discovery description.

Bad:

description: "Follow-up tasks and cleanup items that are not part of an active ExecPlan."

This can surface TODO for queries about active plans because active and ExecPlan are still strong tokens.

Better:

description: "Follow-up tasks and cleanup items; read when looking for deferred implementation work, small backlog items, or candidate topics to promote into a future plan."

Move exclusion details into the body if humans need them. The description should describe the positive route.

Heuristics

• Prefer verbs from expected user requests: create, update, review, implement, debug, validate, route, score.
• Prefer concrete nouns from the repository vocabulary: ExecPlan, frontmatter, match, lint, config, scoring, skills.
• Use path-like scope words only when useful: active plan, completed plan, design doc, skill.
• Keep stable context in descriptions; put volatile status or long rationale in the body.
• If two documents compete, make their descriptions contrast by job, not by negation.

Done Criteria

A description is good enough when:

• expected queries route to the document near the top
• unrelated documents stop appearing because of accidental shared words
• the description remains true when read alone in docgarden match output
• docgarden lint <changed-files> --color never passes