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

| 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 --help for 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/ |