sister-script

Document-first automation — the doc is the source of truth

⭐4stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

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.
namesister-script
descriptionDocument-first automation — the doc is the source of truth
licenseMIT
tier1
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
  1. Start with natural language (PLAY)
  2. Add manual commands (PLAY/LEARN)
  3. Document working procedures (LEARN)
  4. 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 --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
Direction Destination
⬆️ Up skills/
⬆️⬆️ Root Project Root
🎮 Sister play-learn-lift/