straymark-new

name	straymark-new
description	Create StrayMark documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating.

StrayMark New Skill

Create StrayMark documentation based on recent changes.

Instructions

When invoked, follow these steps:

1. Check for Parameters

If the user specified a document type (e.g., /straymark-new ailog), skip to step 4 using that type.

Valid types: ailog, aidec, adr, eth, req, tes, inc, tde, sec, mcard, sbom, dpia

Charter is not a straymark new type. Charters are bounded units of work (filename NN-slug.md, sequential prefix) and have their own command. If the user asks for a Charter (/straymark-new charter, "create a Charter", "declare a Charter"), redirect to /straymark-charter-new.

2. Analyze Context

Gather information about recent changes:

# Get current date
date +%Y-%m-%d

# Get modified files (staged and unstaged)
git status --porcelain

# Summarize the CURRENT work (staged + unstaged + untracked) — label each block,
# do NOT use `HEAD~1`, which describes the previous commit, not current work.
git diff --cached --stat        # staged changes
git diff --stat                 # unstaged changes
git status --porcelain          # includes untracked files
# Only if the user explicitly asks to document an already-committed range:
#   git diff --stat <range>     # e.g. origin/main..HEAD

# Count lines changed in current work
git diff --cached --numstat ; git diff --numstat

# Check code complexity (primary method for AILOG trigger)
straymark analyze --output json 2>/dev/null
# If CLI unavailable, fall back to line count heuristic in step 3

3. Classify and Suggest Type

Based on the analysis, suggest a document type:

Pattern	Suggested Type
Complex code (straymark analyze above_threshold > 0; fallback: >20 lines)	AILOG
Multiple implementation alternatives discussed	AIDEC
Structural/architectural changes, new modules	ADR
Files with auth, user, privacy, gdpr	ETH (draft)
Test files (*.test.*, *.spec.*)	TES
Bug fixes, hotfixes	INC
TODO, FIXME, HACK comments added	TDE (code-smell trigger)
Transversal debt — heritage from prior Charter, applies to multiple modules, requires dedicated Charter, or needs human prioritization	TDE (architectural trigger — distinct from per-Charter R<N>; see AGENT-RULES.md §3)
Requirements or spec files	REQ
Multi-session implementation block (>1 day, >5 tasks, multi-phase)	Charter — redirect to /straymark-charter-new (Charters use straymark charter new, not straymark new)

4. Confirm with User

Always display this confirmation before creating:

╔══════════════════════════════════════════════════════════════════╗
║  StrayMark New                                                    ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                   ║
║  📊 Analysis:                                                     ║
║     • Files modified: [N]                                         ║
║     • Lines changed: [+X / -Y]                                    ║
║     • Area: [detected area or "general"]                          ║
║                                                                   ║
║  🎯 Suggested type: [TYPE] ([Full Name])                          ║
║     Reason: [Brief explanation]                                   ║
║                                                                   ║
║  📝 Proposed filename:                                            ║
║     [TYPE]-YYYY-MM-DD-NNN-[description].md                        ║
║                                                                   ║
╚══════════════════════════════════════════════════════════════════╝

Confirm creation? [Y/n/other type]:

Wait for user confirmation before proceeding.

5. Check Language Configuration

Read .straymark/config.yml to determine language:

language: en  # or es

Use template path based on language:

• en (default): .straymark/templates/TEMPLATE-[TYPE].md
• es: .straymark/templates/i18n/es/TEMPLATE-[TYPE].md

6. Generate Document ID

Determine the next sequence number:

# Find existing documents of this type for today — search RECURSIVELY so nested
# locations (e.g. AILOG/AIDEC/ETH under .straymark/07-ai-audit/...) are not missed.
# A one-level glob like `.straymark/*/` returns 0 for those and causes ID collisions.
find .straymark -type f -name "[TYPE]-$(date +%Y-%m-%d)-*.md" 2>/dev/null | wc -l

ID format: [TYPE]-YYYY-MM-DD-NNN. The next sequence number is the highest existing NNN for today + 1 (not merely count + 1, which is wrong when there are gaps). Use the type→directory table in step 7 to resolve where [TYPE] documents live.

7. Load Template and Create Document

1. Read the appropriate template
2. Replace placeholders:
   • YYYY-MM-DD → Current date
   • NNN → Sequence number (001, 002, etc.)
   • [agent-name-v1.0] → your runtime's canonical agent identity (see AGENT-RULES.md §1 — e.g. claude-code-v1.0, gemini-cli-v1.0, codex-cli-v1.0, cursor-v1.0; do not assume Claude)
3. Fill in context from git analysis
4. Save to correct location:

Type	Location
AILOG	.straymark/07-ai-audit/agent-logs/
AIDEC	.straymark/07-ai-audit/decisions/
ETH	.straymark/07-ai-audit/ethical-reviews/
ADR	.straymark/02-design/decisions/
REQ	.straymark/01-requirements/
TES	.straymark/04-testing/
INC	.straymark/05-operations/incidents/
TDE	.straymark/06-evolution/technical-debt/
SEC	.straymark/08-security/
MCARD	.straymark/09-ai-models/
SBOM	.straymark/07-ai-audit/
DPIA	.straymark/07-ai-audit/ethical-reviews/

7.5. Apply Automatic Review Rules

Before saving, apply these validation rules to the frontmatter:

• If risk_level is high or critical: set review_required: true
• If eu_ai_act_risk is high: set review_required: true
• If document type is SEC, MCARD, or DPIA: set review_required: true

These rules align with the CLI validation rules CROSS-001, CROSS-002, and CROSS-003.

8. Report Result

After creation, display:

✅ StrayMark document created:
   .straymark/[path]/[TYPE]-YYYY-MM-DD-NNN-description.md

   Review required: [yes/no]
   Risk level: [low/medium/high/critical]

Document Type Reference

Type	Full Name	Purpose
ailog	AI Action Log	Record what the AI agent did
aidec	AI Decision	Document a technical decision with alternatives
adr	Architecture Decision Record	Major architectural decisions
eth	Ethical Review	Privacy, bias, responsible AI concerns
req	Requirement	System requirements
tes	Test Plan	Test strategies and plans
inc	Incident Post-mortem	Incident analysis
tde	Technical Debt	Identified technical debt
sec	Security Assessment	Threat modeling and security controls
mcard	Model/System Card	AI model documentation
sbom	Software Bill of Materials	AI component inventory
dpia	Data Protection Impact Assessment	Privacy impact analysis

Edge Cases

1. No git repository: Inform user that git is required for context analysis
2. No changes detected: Ask user to describe what to document
3. User declines: Acknowledge and exit gracefully
4. Invalid type parameter: Show valid types and ask again