sister-script
Document-first automation — the doc is the source of truth
When & Why to Use This Skill
Sister Script is a document-first automation methodology that establishes documentation as the ultimate source of truth for development. By following the 'Play-Learn-Lift' workflow, it ensures that automation is only built upon proven manual procedures. This approach facilitates bidirectional evolution where documentation improves scripts and automation insights refine documentation, utilizing 'sniffable' Python structures to make tools easily discoverable and understandable for both humans and AI agents.
Use Cases
- Converting Manual Procedures to Automation: Systematically transform documented manual steps into reliable scripts once the process is proven stable.
- Maintaining Living Documentation: Ensure that technical documentation and automation scripts stay in sync, preventing the common issue of outdated 'dead' docs.
- Building AI-Ready CLI Tools: Creating Python-based tools with clear 'sniffable' structures that allow LLMs to understand command-line interfaces instantly through docstrings and main() structures.
- Standardizing Operational Workflows: Implementing a consistent methodology for teams to move from experimental 'play' phases to documented 'learn' phases, and finally to automated 'lift' stages.
| name | sister-script |
|---|---|
| description | Document-first automation — the doc is the source of truth |
| license | MIT |
| tier | 1 |
| related | [moollm, play-learn-lift, skill, sniffable-python, plain-text, yaml-jazz, constructionism, postel, debugging] |
| tags | [moollm, automation, documentation, methodology, development] |
Sister Script
Document-first development. Automate only what's proven.
The document is the source of truth. Scripts are its children.
[!TIP] LIFT stage of play-learn-lift. Proven procedures become automation.
The Pattern
graph TD
D[📄 Document] -->|manual test| C[💻 Commands]
C -->|document| P[📋 Procedure]
P -->|automate| S[🤖 Sister Script]
S -->|improve| D
- Start with natural language (PLAY)
- Add manual commands (PLAY/LEARN)
- Document working procedures (LEARN)
- Generate automation (LIFT)
Bidirectional Evolution
- Document → Script: Proven procedures become automated
- Script → Document: Automation insights improve docs
Contents
| File | Purpose |
|---|---|
| SKILL.md | Full methodology documentation |
| PROCEDURE.md.tmpl | Procedure template |
| SISTER.yml.tmpl | Sister relationship template |
The Intertwingularity
Sister-script is the LIFT stage of play-learn-lift — automate proven patterns.
graph LR
SS[👯 sister-script] -->|LIFT stage of| PLL[🎮📚🚀 play-learn-lift]
SS -->|automates| DOC[📄 documents]
SS -->|produces| CODE[🤖 scripts]
RN[📓 research-notebook] -->|feeds| SS
SL[📜 session-log] -->|source for| SS
Sniffable Python: The Structure
Sister scripts should follow sniffable-python/ conventions:
#!/usr/bin/env python3
"""tool-name: One-line description.
Docstring becomes --help AND is visible to LLM.
"""
import argparse
def main():
"""CLI structure — sniff this to understand the tool."""
parser = argparse.ArgumentParser(description=__doc__.split('\n')[0])
# ... CLI tree here ...
args = parser.parse_args()
_dispatch(args)
# Implementation below the fold
Why sniffable Python for sister scripts?
- LLM can read
main()and understand the CLI - Human can run
--helpfor the same info - Single source of truth for documentation
- One sniff and you smell success
Dovetails With
Sister Skills
| Skill | Relationship |
|---|---|
| sniffable-python/ | The structure sister scripts should follow |
| play-learn-lift/ | Sister-script IS the LIFT stage |
| session-log/ | Source material for patterns |
| research-notebook/ | Documented procedures |
| plan-then-execute/ | Scripts can become plans |
Protocol Symbols
| Symbol | Link |
|---|---|
SISTER-SCRIPT |
PROTOCOLS.yml |
BUILD-COMMAND |
PROTOCOLS.yml |
PLAY-LEARN-LIFT |
PROTOCOLS.yml |
Navigation
| Direction | Destination |
|---|---|
| ⬆️ Up | skills/ |
| ⬆️⬆️ Root | Project Root |
| 🎮 Sister | play-learn-lift/ |