8e978fef9d
New: gotchas-skills.md (non-ASCII frontmatter, per-profile skill dirs). Updated: gotchas-bash.md (+((var++)) with zero), decisions.md (+python3 for JSON), process-lessons.md (+cat -A diagnostic). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1.7 KiB
Decisions
OpenSpec format for all script specifications
Every script starts with a spec in specs/<name>.spec.md using OpenSpec format: purpose, usage, behaviour, dryrun behaviour, edge cases, and examples. This project is a testbed for agent-driven development where specs drive implementation and testing.
Mandatory --dryrun / -n on every script
All scripts must support --dryrun which previews actions without side effects. This enables the testing strategy: test scripts exercise the main script's dryrun mode to verify behaviour matches the spec without making real changes.
set -uo pipefail without -e for reporting tools
Read-only/reporting scripts use set -uo pipefail instead of set -euo pipefail. The -e flag causes silent failures in complex pipeline/subshell chains. Explicit error handling is more predictable for tools that aggregate data from many sources.
"No remotes" and "detached HEAD" are not dirty states
In git-status-report, repos with no remotes or detached HEAD are considered clean unless they have local changes. "(no remotes)" is only shown as annotation when the repo already has uncommitted changes.
Use python3 for JSON parsing in bash scripts
Scripts that need to read JSON (e.g., .reflection-state.json) use inline python3 rather than jq or fragile bash string parsing. python3 is reliably available on target systems and handles edge cases (nested keys, unicode, null values) that bash alternatives struggle with.
Project hosted under skynet org
small-scripts lives in the skynet org on Gitea (gitea.oreillyit.nz) as an AI-focused project — specifically a testbed for agent-driven, spec-first development workflows.