Audit and organize workspace documents: $ARGUMENTS
$ARGUMENTS should be one of:
- "audit" — Full audit of all docs in docs/workspace/
- "fix" — Audit and auto-fix all issues found
- A specific section (e.g., "articles") — Audit that section only
- A specific file path — Audit that single file
- Empty — Run full audit
What This Skill Does
The workspace at /workspace reads markdown from docs/workspace/ and renders it in the browser. This skill ensures:
- Frontmatter is clean — Only the right fields, correctly formatted
- No metadata leaks — Status fields, editorial notes, and raw frontmatter never show in the reader
- Sections match directories — Every subdirectory is a sidebar section
- Ordering is intentional —
order field controls sort within each section
- Filenames follow conventions — Lowercase kebab-case, no prefixes,
.md extension
- Content renders correctly — Headings, lists, blockquotes, code, and task lists all work in
workspace-prose
Phase 1: Scan
Read all files in docs/workspace/ recursively:
find docs/workspace -name "*.md" -not -name "README.md" | sort
For each file, extract and check:
Frontmatter Checks
| Field |
Required |
Rules |
title |
Yes |
Non-empty string. Sentence case or title case. No quotes needed unless special chars. |
description |
Yes |
1 sentence, under 120 chars. Shown in sidebar/listing. |
order |
Yes |
Integer. Controls sort within section. |
themes |
Articles only |
Array of valid EEAT theme slugs |
status |
Articles only |
One of: draft, review, published |
audience |
Articles only |
One of: collaborators, internal, public |
author |
Articles only |
Should be "Brad Brisco" |
updated |
Articles only |
ISO date YYYY-MM-DD |
Fields that must NOT appear in non-article docs:
source, url, published_at, content_type, slug — these are article-specific
- Any field not in the table above for the doc type
Content Checks
| Issue |
Detection |
Fix |
| Frontmatter visible in body |
Body starts with --- after the closing --- |
Remove duplicate frontmatter |
| Raw YAML in body |
Lines like status: draft or themes: in body text |
Move to frontmatter or remove |
| Broken frontmatter |
Missing closing --- |
Add closing delimiter |
| Double frontmatter |
Two ---..--- blocks |
Merge into one |
| H1 duplicates title |
First heading matches title field exactly |
Remove the H1 (title is rendered by the viewer) |
| Empty description |
description: "" or missing |
Generate from first paragraph |
| Missing order |
No order field |
Assign based on alphabetical position |
| Invalid theme slug |
Theme not in EEAT taxonomy |
Flag for user review |
Filename Checks
| Issue |
Detection |
Fix |
| Uppercase letters |
[A-Z] in filename |
Rename to lowercase |
| Spaces in filename |
in filename |
Replace with - |
| Underscores |
_ in filename |
Replace with - |
Prefix brad-brisco- |
Starts with brad-brisco- |
Strip prefix |
| Non-.md extension |
.mdx, .markdown, etc. |
Rename to .md |
Section Checks
| Issue |
Detection |
Fix |
| Orphan file |
.md in docs/workspace/ root (not in a subdirectory) |
Move to appropriate section or flag |
| Empty section |
Directory with no .md files |
Flag for removal or content |
| Unknown section |
Directory not in expected set |
Flag for user review |
Expected sections (see docs/workspace/README.md and WORKSPACE_SECTION_ORDER in src/lib/workspace/docs.ts):
articles — Covocational articles
author — Voice identity, writing prompts, digital profile
books — Published books and e-book manuscripts
ideas — Notes and brainstorms
insights — Content pipeline, EEAT, gap analysis, playbooks
meta — Conventions, templates, article index (sidebar: Editorial)
podcasts — Podcast notes
projects — Active project documents
research — Research notes and bibliography
videos — Video scripts and outlines
Phase 2: Report
Present findings as a table:
## Audit Results
### Issues Found: N
| File | Issue | Severity | Auto-fixable |
|------|-------|----------|-------------|
| ... | ... | error/warn | yes/no |
### Section Summary
| Section | Docs | All Clean | Issues |
|---------|------|-----------|--------|
| articles | 15 | ✓ | 0 |
| ... | ... | ... | ... |
Severity levels:
- error — Will break rendering or leak metadata (auto-fix if possible)
- warn — Should be fixed but won't break anything
- info — Suggestion for improvement
Phase 3: Fix (if requested)
For each auto-fixable issue:
- Show the proposed change
- Apply with Edit tool
- Mark as fixed in the report
For non-auto-fixable issues, explain what the user needs to decide.
Phase 4: Verify Sidebar Rendering
After fixes, verify the API returns clean data:
- Read
src/lib/workspace/docs.ts to understand how the scanner works
- Confirm every section directory is scanned
- Confirm every file has valid frontmatter that the scanner can parse
- Confirm
title and description are the ONLY fields surfaced in the sidebar listing
- Confirm no raw content or metadata appears in the sidebar (only title + description)
Frontend-Safe Content Rules
These rules ensure clean rendering in the workspace-prose class:
No frontmatter in body — The viewer strips frontmatter via gray-matter. If there's a second --- block, it renders as an <hr> and raw YAML text.
No editorial metadata in prose — Lines like Status: draft, Audience: internal, or Updated: 2026-04-07 must ONLY live in frontmatter, never in the body.
H1 is optional in body — The doc viewer renders the title field as the page heading. If the body also has an # H1, it creates a duplicate. Prefer starting body content with H2 or a lead paragraph.
Task lists render — - [ ] and - [x] are styled by workspace-prose. Use them freely.
Tables render — Standard GFM tables work. workspace-prose styles them with Inter label font.
Blockquotes render — > blockquotes are styled. Use > **Practice:** for callouts.
Code blocks render — Fenced code blocks with language tags work. Inline code is styled.
Images need relative paths — Use  or absolute URLs. No broken image refs.
Internal links — Use relative paths from the file's location. e.g., [Voice Guide](../author/voice-identity.md)
Quick Commands
Audit everything
/workspace-organize audit
Fix a specific section
/workspace-organize fix articles
Check a single file before committing
/workspace-organize docs/workspace/articles/new-article.md
1---2name: workspace-organize3description: "Audit and fix workspace doc organization — frontmatter hygiene, section placement, sidebar rendering, and frontend-safe content. Ensures docs/workspace/ files render cleanly with no metadata leaking into the reader view. Use when adding docs, reorganizing sections, or before deploying."4user-invocable: true5allowed-tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite6metadata:7 source: https://skillmd.com/skills/joshuashepherd/workspace-organize8---910Audit and organize workspace documents: $ARGUMENTS1112$ARGUMENTS should be one of:13- "audit" — Full audit of all docs in docs/workspace/14- "fix" — Audit and auto-fix all issues found15- A specific section (e.g., "articles") — Audit that section only16- A specific file path — Audit that single file17- Empty — Run full audit1819## What This Skill Does2021The workspace at `/workspace` reads markdown from `docs/workspace/` and renders it in the browser. This skill ensures:22231. **Frontmatter is clean** — Only the right fields, correctly formatted242. **No metadata leaks** — Status fields, editorial notes, and raw frontmatter never show in the reader253. **Sections match directories** — Every subdirectory is a sidebar section264. **Ordering is intentional** — `order` field controls sort within each section275. **Filenames follow conventions** — Lowercase kebab-case, no prefixes, `.md` extension286. **Content renders correctly** — Headings, lists, blockquotes, code, and task lists all work in `workspace-prose`2930## Phase 1: Scan3132Read all files in `docs/workspace/` recursively:3334```bash35find docs/workspace -name "*.md" -not -name "README.md" | sort36```3738For each file, extract and check:3940### Frontmatter Checks4142| Field | Required | Rules |43|-------|----------|-------|44| `title` | Yes | Non-empty string. Sentence case or title case. No quotes needed unless special chars. |45| `description` | Yes | 1 sentence, under 120 chars. Shown in sidebar/listing. |46| `order` | Yes | Integer. Controls sort within section. |47| `themes` | Articles only | Array of valid EEAT theme slugs |48| `status` | Articles only | One of: `draft`, `review`, `published` |49| `audience` | Articles only | One of: `collaborators`, `internal`, `public` |50| `author` | Articles only | Should be "Brad Brisco" |51| `updated` | Articles only | ISO date YYYY-MM-DD |5253**Fields that must NOT appear in non-article docs:**54- `source`, `url`, `published_at`, `content_type`, `slug` — these are article-specific55- Any field not in the table above for the doc type5657### Content Checks5859| Issue | Detection | Fix |60|-------|-----------|-----|61| Frontmatter visible in body | Body starts with `---` after the closing `---` | Remove duplicate frontmatter |62| Raw YAML in body | Lines like `status: draft` or `themes:` in body text | Move to frontmatter or remove |63| Broken frontmatter | Missing closing `---` | Add closing delimiter |64| Double frontmatter | Two `---..---` blocks | Merge into one |65| H1 duplicates title | First heading matches `title` field exactly | Remove the H1 (title is rendered by the viewer) |66| Empty description | `description: ""` or missing | Generate from first paragraph |67| Missing order | No `order` field | Assign based on alphabetical position |68| Invalid theme slug | Theme not in EEAT taxonomy | Flag for user review |6970### Filename Checks7172| Issue | Detection | Fix |73|-------|-----------|-----|74| Uppercase letters | `[A-Z]` in filename | Rename to lowercase |75| Spaces in filename | ` ` in filename | Replace with `-` |76| Underscores | `_` in filename | Replace with `-` |77| Prefix `brad-brisco-` | Starts with `brad-brisco-` | Strip prefix |78| Non-.md extension | `.mdx`, `.markdown`, etc. | Rename to `.md` |7980### Section Checks8182| Issue | Detection | Fix |83|-------|-----------|-----|84| Orphan file | `.md` in `docs/workspace/` root (not in a subdirectory) | Move to appropriate section or flag |85| Empty section | Directory with no `.md` files | Flag for removal or content |86| Unknown section | Directory not in expected set | Flag for user review |8788**Expected sections** (see `docs/workspace/README.md` and `WORKSPACE_SECTION_ORDER` in `src/lib/workspace/docs.ts`):89- `articles` — Covocational articles90- `author` — Voice identity, writing prompts, digital profile91- `books` — Published books and e-book manuscripts92- `ideas` — Notes and brainstorms93- `insights` — Content pipeline, EEAT, gap analysis, playbooks94- `meta` — Conventions, templates, article index (sidebar: Editorial)95- `podcasts` — Podcast notes96- `projects` — Active project documents97- `research` — Research notes and bibliography98- `videos` — Video scripts and outlines99100## Phase 2: Report101102Present findings as a table:103104```105## Audit Results106107### Issues Found: N108109| File | Issue | Severity | Auto-fixable |110|------|-------|----------|-------------|111| ... | ... | error/warn | yes/no |112113### Section Summary114115| Section | Docs | All Clean | Issues |116|---------|------|-----------|--------|117| articles | 15 | ✓ | 0 |118| ... | ... | ... | ... |119```120121Severity levels:122- **error** — Will break rendering or leak metadata (auto-fix if possible)123- **warn** — Should be fixed but won't break anything124- **info** — Suggestion for improvement125126## Phase 3: Fix (if requested)127128For each auto-fixable issue:1291. Show the proposed change1302. Apply with Edit tool1313. Mark as fixed in the report132133For non-auto-fixable issues, explain what the user needs to decide.134135## Phase 4: Verify Sidebar Rendering136137After fixes, verify the API returns clean data:1381391. Read `src/lib/workspace/docs.ts` to understand how the scanner works1402. Confirm every section directory is scanned1413. Confirm every file has valid frontmatter that the scanner can parse1424. Confirm `title` and `description` are the ONLY fields surfaced in the sidebar listing1435. Confirm no raw content or metadata appears in the sidebar (only title + description)144145## Frontend-Safe Content Rules146147These rules ensure clean rendering in the `workspace-prose` class:1481491. **No frontmatter in body** — The viewer strips frontmatter via `gray-matter`. If there's a second `---` block, it renders as an `<hr>` and raw YAML text.1501512. **No editorial metadata in prose** — Lines like `Status: draft`, `Audience: internal`, or `Updated: 2026-04-07` must ONLY live in frontmatter, never in the body.1521533. **H1 is optional in body** — The doc viewer renders the `title` field as the page heading. If the body also has an `# H1`, it creates a duplicate. Prefer starting body content with H2 or a lead paragraph.1541554. **Task lists render** — `- [ ]` and `- [x]` are styled by `workspace-prose`. Use them freely.1561575. **Tables render** — Standard GFM tables work. `workspace-prose` styles them with Inter label font.1581596. **Blockquotes render** — `>` blockquotes are styled. Use `> **Practice:**` for callouts.1601617. **Code blocks render** — Fenced code blocks with language tags work. Inline `code` is styled.1621638. **Images need relative paths** — Use `` or absolute URLs. No broken image refs.1641659. **Internal links** — Use relative paths from the file's location. e.g., `[Voice Guide](../author/voice-identity.md)`166167## Quick Commands168169### Audit everything170```171/workspace-organize audit172```173174### Fix a specific section175```176/workspace-organize fix articles177```178179### Check a single file before committing180```181/workspace-organize docs/workspace/articles/new-article.md182```