1---2name: localsetup-script-and-docs-quality3description: Markdown/encoding standards, script generation quality, file creation discipline, documentation discipline. Use when generating scripts, creating/editing markdown or docs.4---5
6# Script and docs quality
7
8## 15. Markdown compatibility (CRITICAL)
9
10- **ASCII-first:** No Unicode emoji, box-drawing, or arrow symbols in markdown. Use [OK], [FAIL], [WARNING], [YES], [NO]; use -> not arrow; use * or - for bullets.
11- **No EM dash:** Do not use the EM dash character (—, U+2014) in any user-facing text. Use a space and hyphen ( - ) or a plain hyphen instead.
12- **Encoding:** UTF-8; prefer pure ASCII. Verify in markdown preview before committing.
13
14## 16. Script generation quality (all languages)
15
16- **Comments:** Header with purpose, usage, parameters; document each function; descriptive names.
17- **Error handling:** Try-catch (or equivalent); validate inputs; check prerequisites; no silent failures.
18- **STDOUT:** All scripts output to console; pipeable; STDOUT for normal, STDERR for errors.
19- **Structure:** Break into functions; clear error messages with source/trace; actionable guidance.
20- **Bash:** set -euo pipefail, trap for cleanup. **Python:** type hints, docstrings, context managers. **PowerShell:** try/catch/finally, Write-* cmdlets.
21
22## 17. External input hardening (mandatory)
23
24- Treat every external input as hostile: CLI arguments, filesystem content, network payloads, copied text, imported archives.
25- Sanitize untrusted strings before parsing and before printing: strip control characters, normalize whitespace, enforce max length.
26- Validate type, schema, and allowed ranges before use; reject invalid values with clear error text.
27- Exception handling must be explicit and actionable: print source, exception type, and message to STDERR; return non-zero exit when task cannot continue.
28- Never swallow errors (`except: pass`, silent `|| true` on critical operations). Partial-failure mode is allowed only when warnings are emitted and processing decisions are explicit.
29
30## 7. File creation discipline
31
32- Before creating any file: verify it belongs; minimal approach; "Is this essential?" Consolidate rather than duplicate.
33
34## 2. Documentation discipline
35
36- **_localsetup/docs/ is ONLY for framework documentation.** Not for IDE setup or external tool guides. All docs must have status (ACTIVE/PROPOSAL/DRAFT/DEPRECATED/ARCHIVED). Check status before assuming a feature is implemented. See [DOCUMENT_LIFECYCLE_MANAGEMENT.md](../../docs/DOCUMENT_LIFECYCLE_MANAGEMENT.md).
37- **Platform default for any generated docs/output:** Use rich markdown (code blocks, lists, typography, links for in-repo refs, glyphs where they help), humanized prose. See [OUTPUT_AND_DOC_GENERATION.md](../../docs/OUTPUT_AND_DOC_GENERATION.md).