flonat-research 0.1.0

package/skills/learn/scripts/validate_skill.py

@@ -0,0 +1,265 @@
+"""Validate a skill directory against conventions.
+
+Checks frontmatter, naming, description quality, body length,
+referenced files, and allowed_tools format.
+
+Usage:
+    uv run python validate_skill.py <skill-directory> [--strict] [--all]
+
+Exit codes: 0 = valid, 1 = errors found, 2 = warnings promoted by --strict.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("pyyaml not installed. Run: uv pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+_NAME_PATTERN = re.compile(r"^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$")
+_PLACEHOLDER_PATTERNS = (
+    re.compile(r"\bTODO\b", re.IGNORECASE),
+    re.compile(r"\bplaceholder\b", re.IGNORECASE),
+    re.compile(r"\bFIXME\b", re.IGNORECASE),
+    re.compile(r"\bXXX\b"),
+)
+_KNOWN_TOOLS = {
+    "Read", "Write", "Edit", "Glob", "Grep", "Bash",
+    "AskUserQuestion", "Task", "WebFetch", "WebSearch",
+    "NotebookEdit", "EnterPlanMode", "ExitPlanMode", "Skill",
+}
+
+
+def _split_frontmatter(content: str) -> tuple[str, str]:
+    """Split SKILL.md into frontmatter string and body."""
+    lines = content.split("\n")
+    start = 0
+    while start < len(lines) and lines[start].strip() == "":
+        start += 1
+    if start >= len(lines) or lines[start].strip() != "---":
+        return "", ""
+    close = None
+    for i in range(start + 1, len(lines)):
+        if lines[i].strip() == "---":
+            close = i
+            break
+    if close is None:
+        return "", ""
+    frontmatter_str = "\n".join(lines[start + 1 : close])
+    body = "\n".join(lines[close + 1 :]).strip()
+    return frontmatter_str, body
+
+
+def _parse_yaml(frontmatter_str: str) -> dict | None:
+    """Parse YAML frontmatter."""
+    try:
+        data = yaml.safe_load(frontmatter_str)
+        return data if isinstance(data, dict) else None
+    except yaml.YAMLError:
+        return None
+
+
+def _has_placeholder(text: str) -> bool:
+    return any(p.search(text) for p in _PLACEHOLDER_PATTERNS)
+
+
+def _count_body_lines(body: str) -> int:
+    return len([line for line in body.split("\n") if line.strip()])
+
+
+def validate_skill(path: Path, strict: bool = False) -> tuple[bool, list[str], list[str]]:
+    """Validate a skill directory.
+
+    Returns (is_valid, errors, warnings).
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    skill_dir = Path(path)
+
+    # --- SKILL.md exists ---
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        errors.append("SKILL.md not found.")
+        return (False, errors, warnings)
+
+    content = skill_md.read_text()
+
+    # --- Valid frontmatter ---
+    frontmatter_str, body = _split_frontmatter(content)
+    if not frontmatter_str:
+        errors.append("Missing or invalid YAML frontmatter (needs --- delimiters).")
+        return (False, errors, warnings)
+
+    data = _parse_yaml(frontmatter_str)
+    if data is None:
+        errors.append("Frontmatter is not valid YAML.")
+        return (False, errors, warnings)
+
+    # --- Body non-empty ---
+    if not body:
+        errors.append("Body (system prompt) is empty.")
+
+    # --- Name present and valid ---
+    name = data.get("name")
+    if not name or not isinstance(name, str):
+        errors.append("Required field 'name' is missing.")
+    elif not _NAME_PATTERN.match(name):
+        errors.append(f"Invalid name '{name}': must be lowercase alphanumeric + hyphens, 1-64 chars.")
+    else:
+        if name != skill_dir.name:
+            errors.append(f"Name '{name}' does not match directory '{skill_dir.name}'.")
+
+    if isinstance(name, str) and _has_placeholder(name):
+        errors.append(f"Name '{name}' contains placeholder text.")
+
+    # --- Description present and useful ---
+    description = data.get("description")
+    if not description or not isinstance(description, str):
+        errors.append("Required field 'description' is missing.")
+    else:
+        desc_clean = description.replace("\n", " ").strip()
+        if len(desc_clean) > 1024:
+            errors.append(f"Description too long ({len(desc_clean)} chars, max 1024).")
+        if _has_placeholder(desc_clean):
+            errors.append("Description contains placeholder text.")
+        if len(desc_clean) < 20:
+            warnings.append(f"Description very short ({len(desc_clean)} chars) — may not trigger correctly.")
+        if not any(kw in desc_clean.lower() for kw in ("use when", "use for", "use this", "when ")):
+            warnings.append("Description lacks activation hint (e.g., 'Use when...'). May not trigger reliably.")
+
+    # --- Body quality ---
+    if body:
+        line_count = _count_body_lines(body)
+        if line_count < 5:
+            warnings.append(f"Body is very short ({line_count} non-empty lines).")
+        if line_count > 300:
+            warnings.append(f"Body is long ({line_count} lines). Consider moving detail to references/.")
+
+    # --- allowed_tools / allowed-tools ---
+    tools = data.get("allowed_tools") or data.get("allowed-tools")
+    if tools and isinstance(tools, list):
+        for tool in tools:
+            if isinstance(tool, str):
+                # Strip Bash(pattern) to just Bash for the check
+                base = tool.split("(")[0]
+                if base not in _KNOWN_TOOLS:
+                    warnings.append(f"Unknown tool '{tool}' in allowed_tools.")
+
+    # --- Referenced files exist ---
+    refs_dir = skill_dir / "references"
+    scripts_dir = skill_dir / "scripts"
+    # Check for broken relative links in body (strip #anchors before checking)
+    for match in re.finditer(r'\[.*?\]\(((?!http)[^)]+)\)', body):
+        rel_path = match.group(1)
+        file_path_str = rel_path.split("#")[0]  # strip fragment
+        if not file_path_str or file_path_str.startswith("<"):  # skip placeholders like <name>.md
+            continue
+        full_path = skill_dir / file_path_str
+        if not full_path.exists():
+            errors.append(f"Broken link: '{rel_path}' — file '{file_path_str}' does not exist.")
+
+    # Check that references/ and scripts/ dirs, if linked to, actually exist
+    # Only flag when there's a markdown link pointing into these dirs
+    refs_link = re.search(r'\]\(references/', body)
+    scripts_link = re.search(r'\]\(scripts/', body)
+    if refs_link and not refs_dir.exists():
+        warnings.append("Body links to 'references/' but directory does not exist.")
+    if scripts_link and not scripts_dir.exists():
+        warnings.append("Body links to 'scripts/' but directory does not exist.")
+
+    # --- Determine validity ---
+    if strict:
+        is_valid = len(errors) + len(warnings) == 0
+    else:
+        is_valid = len(errors) == 0
+
+    return (is_valid, errors, warnings)
+
+
+def _color(text: str, code: str) -> str:
+    return f"\033[{code}m{text}\033[0m"
+
+
+def print_report(skill_path: Path, errors: list[str], warnings: list[str], strict: bool) -> None:
+    print(f"\n  Validating: {skill_path.name}")
+
+    if not errors and not warnings:
+        print(f"  {_color('PASS', '32')}  All checks passed.\n")
+        return
+
+    for err in errors:
+        print(f"  {_color('ERROR', '31')}  {err}")
+
+    for warn in warnings:
+        label = "ERROR" if strict else "WARN "
+        color = "31" if strict else "33"
+        print(f"  {_color(label, color)}  {warn}")
+
+    total = len(errors) + (len(warnings) if strict else 0)
+    if total > 0:
+        print(f"  {_color(f'{total} issue(s)', '31')}\n")
+    else:
+        print(f"  {_color('PASS', '32')}  {len(warnings)} warning(s)\n")
+
+
+def main() -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Validate skill directories.")
+    parser.add_argument("skill_directory", nargs="?", type=Path, help="Path to skill directory")
+    parser.add_argument("--strict", action="store_true", help="Promote warnings to errors")
+    parser.add_argument("--all", action="store_true", help="Validate all skills in the parent directory")
+    args = parser.parse_args()
+
+    if args.all:
+        # Find skills root: if inside a skill dir, go up; otherwise use cwd
+        if args.skill_directory:
+            skills_root = args.skill_directory.resolve()
+        else:
+            skills_root = Path.cwd()
+
+        total_errors = 0
+        total_warnings = 0
+        total_pass = 0
+        total_fail = 0
+
+        for child in sorted(skills_root.iterdir()):
+            if not child.is_dir() or child.name == "shared" or child.name.startswith("."):
+                continue
+            skill_md = child / "SKILL.md"
+            if not skill_md.exists():
+                continue
+
+            is_valid, errors, warnings = validate_skill(child, strict=args.strict)
+            print_report(child, errors, warnings, strict=args.strict)
+            total_errors += len(errors)
+            total_warnings += len(warnings)
+            if is_valid:
+                total_pass += 1
+            else:
+                total_fail += 1
+
+        print(f"  Summary: {total_pass} passed, {total_fail} failed, {total_warnings} warnings\n")
+        return 1 if total_fail > 0 else 0
+
+    if not args.skill_directory:
+        parser.error("skill_directory is required unless --all is used")
+
+    skill_path = args.skill_directory.resolve()
+    if not skill_path.is_dir():
+        print(f"Error: '{skill_path}' is not a directory.", file=sys.stderr)
+        return 1
+
+    is_valid, errors, warnings = validate_skill(skill_path, strict=args.strict)
+    print_report(skill_path, errors, warnings, strict=args.strict)
+
+    if not is_valid:
+        return 2 if (not errors and args.strict) else 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/lessons-learned/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: lessons-learned
+description: "Use when you need a structured post-mortem after incidents, mistakes, or stuck sessions."
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+# Lessons Learned: Structured Retrospective
+
+Analyse incidents using a structured framework, identify root causes, and encode preventive measures directly into skills, guards, or documentation. The goal is systematic improvement, not blame.
+
+## When to Use
+
+- After incidents, mistakes, rollbacks, or near-misses
+- When the user says "what went wrong", "lessons learned", "post-mortem", "retrospective", or "how do we prevent this"
+- After a stuck session where significant time was lost
+- After a wrong-approach event (plan existed but execution diverged)
+
+## Process
+
+### Phase 1: Incident Definition
+
+Capture the facts first, analysis later.
+
+```markdown
+## Incident Summary
+
+**What happened:** [Factual description]
+**When:** [Date/time]
+**Impact:** [What was affected, scope]
+**Resolution:** [How it was fixed/rolled back]
+**Time to resolution:** [How long to fix]
+```
+
+### Phase 2: Timeline Reconstruction
+
+Build a chronological sequence of events:
+
+| Time | Action | Actor | Outcome |
+|------|--------|-------|---------|
+| HH:MM | [What was done] | [Claude/User] | [Result] |
+
+Key questions:
+- What was the trigger?
+- Where did the sequence diverge from expected?
+- What was the point of no return?
+
+### Phase 3: Root Cause Analysis (5 Whys)
+
+```
+1. Why did [incident] happen?
+   → Because [immediate cause]
+
+2. Why did [immediate cause] happen?
+   → Because [deeper cause]
+
+3. Why did [deeper cause] happen?
+   → Because [systemic issue]
+
+4. Why did [systemic issue] exist?
+   → Because [process gap]
+
+5. Why did [process gap] exist?
+   → Because [root cause]
+```
+
+Stop when you reach a cause that can be addressed by a concrete change to the system (skill, rule, hook, doc).
+
+### Phase 4: Contributing Factors
+
+Identify all factors, not just the root cause:
+
+| Category | Factor | Contribution |
+|----------|--------|--------------|
+| **Process** | Missing checkpoint, unclear workflow | [How it contributed] |
+| **Communication** | Ambiguous instructions, assumed consent | [How it contributed] |
+| **Technical** | Missing guard, no validation | [How it contributed] |
+| **Context** | Session continuation, prior assumptions | [How it contributed] |
+| **Human** | Fatigue, time pressure, overconfidence | [How it contributed] |
+
+### Phase 5: Fix Classification
+
+Classify each fix by type:
+
+| Fix Type | When to Use | How to Encode |
+|----------|-------------|---------------|
+| **Skill** | Recurring workflow needs structure | Create SKILL.md via `/learn` |
+| **Guard** | Action requires mandatory checkpoint | Add approval gate to existing skill |
+| **Rule** | Behavioural constraint needed globally | Create `.claude/rules/*.md` |
+| **Documentation** | Knowledge gap caused the issue | Update CLAUDE.md, MEMORY.md, or docs/ |
+| **Hook** | Manual step was forgotten | Create script in hooks/ |
+| **Checklist** | Multiple steps need verification | Add to existing skill |
+
+### Phase 6: Fix Implementation
+
+**Implement fixes during the retrospective, not after.** This is the critical difference from a report-only post-mortem.
+
+For each fix:
+1. Implement it (create/edit the file)
+2. Record what was done:
+
+| Fix | Type | Location | Status |
+|-----|------|----------|--------|
+| [Description] | Skill/Guard/Rule/Doc/Hook | [File path] | Created/Updated |
+
+Also record a `[LEARN]` tag in MEMORY.md for each key correction (per the `learn-tags` rule).
+
+### Phase 7: Verification
+
+Define how to verify the fix works:
+
+```markdown
+## Verification
+
+**Test scenario:** [How to test the fix]
+**Success criteria:** [What "fixed" looks like]
+**Review date:** [When to check if fix is working — default: 2 weeks]
+```
+
+## Output
+
+Write the report to `log/incidents/YYYY-MM-DD_short-description.md`:
+
+```markdown
+# Lessons Learned: [Incident Title]
+
+**Date:** YYYY-MM-DD
+**Severity:** [Low|Medium|High|Critical]
+**Status:** [Resolved|Monitoring|Open]
+
+## Incident Summary
+[Brief description]
+
+## Timeline
+| Time | Action | Actor | Outcome |
+|------|--------|-------|---------|
+
+## Root Cause
+[The fundamental issue]
+
+## Contributing Factors
+- [Factor 1]
+- [Factor 2]
+
+## Fixes Implemented
+| Fix | Type | Location | Status |
+|-----|------|----------|--------|
+
+## Prevention
+[How this prevents recurrence]
+
+## Lessons
+1. [Key takeaway 1]
+2. [Key takeaway 2]
+```
+
+Create `log/incidents/` if it doesn't exist.
+
+## Common Incident Patterns
+
+| Pattern | Symptom | Root Cause | Typical Fix |
+|---------|---------|------------|-------------|
+| Premature action | Action taken before approval | Implied consent ≠ explicit | Add approval gate to skill |
+| Sequence error | Steps in wrong order | Missing dependency chain | Encode sequence in skill |
+| Missing validation | Bad data passed through | No checkpoint | Add pre-flight check |
+| Context carryover | Stale assumptions from prior session | State assumed to persist | Explicit context verification |
+| Scope creep | Did more than requested | Task scope too broad | Clarifying questions first |
+| Planning loop | Re-planned instead of executing | Perfectionism / uncertainty | Execution stall detector |
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Instead |
+|--------------|---------|---------|
+| Blame assignment | Creates defensiveness | Focus on process, not people |
+| Single-cause thinking | Oversimplifies | Use 5 Whys, multiple factors |
+| Recommend without acting | Lessons forgotten, recurs | Implement fixes during retro |
+| Vague fixes ("be more careful") | Not verifiable | Encode specific changes |
+| Skip verification | No way to know if fix worked | Define success criteria |
+
+## Cross-References
+
+- **`[LEARN]` tags** — record one-liner corrections in MEMORY.md (the quick complement to this skill)
+- **`/learn`** — extract a full skill from a session (when the fix type is "Skill")
+- **`/ideas`** — if a fix is too large for this session, capture as an idea for later
+
+## Success Criteria
+
+The retrospective is complete when:
+- [ ] Incident clearly defined with timeline
+- [ ] Root cause identified (not just symptoms)
+- [ ] Contributing factors documented
+- [ ] At least one fix implemented (not just recommended)
+- [ ] Fix encoded in appropriate location (skill, rule, hook, doc)
+- [ ] `[LEARN]` tags recorded in MEMORY.md
+- [ ] Verification criteria defined
+- [ ] Report written to `log/incidents/`