writing-plans

<execution_workflow> Execute these steps strictly in order. DO NOT announce the skill unless specifically asked. Do not write implementation code in this phase; isolated worktree setup belongs to the execution phase.

1. PRE-FLIGHT CONTEXT (MANDATORY — before any planning output):

   • SECURITY STANDARD LOAD: Read .sumela/skills/secure-coding-standard/SKILL.md if not already in context. EVERY plan gets this — not just "security-flavored" ones — because the plan's Security Constraints header and each task's implementation steps must be authored against the actual standard, never from memory. Skipping this because "the feature has no auth surface" is a forbidden rationalization: input validation, error handling, and data exposure apply to all code.
   • PHASE RULE SYNC: This skill activates the planning phase. Per .sumela/RULE_REGISTRY.md <phase_to_rule_matrix>, confirm every universal rule, every planning-phase rule, and every rule matching the active stack scope(s) and domain(s) is loaded — READ any missing rule file now, before drafting. If the registry file is missing, tell the user to run setup — do not guess the matrix.

2. SCOPE & FILE MAPPING:

   • SECOND BRAIN CHECK (MANDATORY): Read wiki/architecture-decisions.md and wiki/tech-debt-and-known-issues.md. The plan MUST respect existing approved AD records and account for open TD items that overlap with the feature scope. Reference relevant AD-XX / TD-XX IDs in the plan header's Architecture section.
   • Analyze spec: If it covers multiple independent subsystems, STOP and suggest breaking it into separate plans (one per subsystem).
   • Map files: Determine exact file paths to create or modify. Enforce single responsibility. Split large files if necessary. Files that change together live together — split by responsibility, not by technical layer.
   • DEPENDENCY GRAPH: Map what depends on what before ordering tasks. Implementation order follows the graph bottom-up — build foundations first (e.g., DB schema → domain entities → application services → API endpoints → frontend clients → UI components). Never build a layer before its dependency exists.

3. INITIALIZE PLAN DOCUMENT:

   • Save path: docs/second-brain/artifacts/plans/YYYY-MM-DD-<feature-name>.md
   • WRITE-TOOL RULE: Create the plan with the IDE's file-write tool (NOT shell redirection / heredoc), so the IDE's change tracker registers it.
   • VISIBILITY CHECK (MANDATORY, immediately after saving): Run git check-ignore -q <save-path> and decide on the EXIT CODE only: exit 1 = visible → PASS (exit 1 is success, NOT a command error); exit 0 = ignored → remediate. Do NOT decide from -v output alone — a -v match whose pattern starts with ! means the file IS visible. On exit 0: run -v to name the culprit (common cause: a generic artifacts/ build-output pattern), append !docs/second-brain/artifacts/ and !docs/second-brain/artifacts/** at the END of the .gitignore in the SumelaOS install root (the directory containing docs/second-brain/), re-run the -q check, and tell the user what you fixed. If the lines already existed, re-append them at the END anyway (duplicates are harmless; last match wins). If STILL ignored (an excluded parent like docs/ — negation cannot pierce it), STOP and warn the user: the plan is invisible to git status and the IDE's Changes view; ask how to resolve.
   • MUST include this exact header:

     # [Feature Name] Implementation Plan
     > **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` or `executing-plans`. Steps use checkbox (`- [ ]`) syntax. 
     > **CRITICAL RULE:** Accumulate uncommitted changes. DO NOT use `git commit` during task execution. Only `git add` is allowed until the final review step.
     **Goal:** [One sentence]
     **Architecture:** [2-3 sentences]
     **Tech Stack:** [Key technologies]
     **TDD Mode:** [Explicitly state if TDD is Enabled or Skipped based on user's prior choice]
     **Security Constraints:** [List specific threat boundaries, input validation, or Auth needs. MANDATORY: Code must comply with `secure-coding-standard`.]
     
     ## Risks & Mitigations
     | Risk | Impact | Mitigation |
     |------|--------|------------|
     | [Risk] | High/Med/Low | [Strategy] |
     
     ## Open Questions
     - [Any question requiring human input before or during implementation]