Spatial Navigation Memory Coach

SKILL.md — Skill Registry & Architecture

Overview

spatial-navigation-memory-coach is a production-grade harness skill that transforms Claude into a domain expert in Spatial Cognition & Navigation Memory Training. It implements a rigorous, evidence-backed workflow that combines real-time data aggregation, recognized domain methods, academic research integration, and continuous knowledge improvement into a single orchestrated system with enforced quality gates.

Skill Architecture

Harness Pattern

The skill implements a Sequential Sub-Skill Orchestration Pattern with quality gates at each step:

USER INPUT
    │
    ▼
[LANGUAGE DETECTION]
    │
    ├─► Step 1: sub-gather-requirements     → Structured requirements
    ├─► Step 2: sub-evidence-collector      → Evidence bundle
    ├─► Step 3: sub-core-analysis           → Domain-specific analysis
    ├─► Step 4: sub-knowledge-updater       → Academic evidence citations
    ├─► Step 5: sub-advisor                 → Synthesis & recommendation
    │
    └─► [QUALITY GATE VALIDATION]           → 10 gates (U1-U6, G1-G4)
            │
            └─► FINAL OUTPUT (only if all critical gates pass)

Flexible Architecture Principles

The skill architecture is designed for flexibility while maintaining production-grade reliability:

1. Sub-Skill Modularity: Each sub-skill is independently executable with clear input/output contracts
2. Graceful Degradation: 5-level degradation system ensures useful output even with partial data
3. Quality Gate Enforcement: Auto-fix with retry limits ensures standards without blocking useful output
4. State Synchronization: All sub-skills share a common context object for coordinated state
5. Event-Driven Logging: Each major step emits structured events for monitoring and debugging

Skill Registration

Registration Process

Skills in this architecture are registered through a three-layer system:

1. Metadata Registration (Always Loaded)

Skill metadata is defined in the YAML frontmatter of SKILL.md:

---
name: spatial-navigation-memory-coach
description: [comprehensive trigger description]
version: 1.0.0
author: Skill 181 Development Team
compatibility: Claude Code 1.0+, Claude.ai
---

Triggering Logic: The description field is the primary mechanism for skill invocation. Claude analyzes user prompts against available skill descriptions to determine which skills to consult.

2. Body Registration (Loaded on Trigger)

The skill body (sections below) contains:

• Execution protocol
• Sub-skill catalog
• Tool requirements
• Quality gate definitions
• Output templates

This content is loaded when the skill is triggered and must remain under 500 lines for performance.

3. Resource Registration (Loaded on Demand)

Bundled resources are referenced but not automatically loaded:

• /references/*.md — Domain knowledge and templates
• /assets/*.json — Schemas and static data
• /scripts/*.py — Executable automation tools

Skill Resolution

When a user prompt is received, the resolution process follows these steps:

1. Parse user prompt for intent and keywords
2. Match against skill descriptions in available_skills
3. Load SKILL.md body for matching skills (ranked by relevance)
4. Execute harness protocol with sub-skill invocations
5. Validate output against quality gates
6. Return final result or degradation notice

Sub-Skill Registration

Each sub-skill is registered in the main harness via:

1. File Location: skills/sub-{name}.md
2. Frontmatter: YAML with name and description
3. Invocation: Skill("sub-{name}") from main harness
4. Input Contract: Defined in sub-skill ## Role & Persona section
5. Output Contract: Defined in sub-skill ## Output Format section

Sub-skills are discovered dynamically at runtime based on the file structure.

Execution Flow

1. Pre-Flight: Language Detection

Before any analysis, detect the user's preferred language:

Detection Method:

• Vietnamese (vi): Presence of Vietnamese characters and domain terms
• English (en): Default
• Other: Default to English and request confirmation

Storage: Detected language stored in LANG variable for all subsequent operations.

Translation Table: Comprehensive field label translations maintained for bilingual output.

2. Step-by-Step Execution

Each step follows a strict protocol:

### Step N: {sub-skill-name}

**Objective**: [One-sentence goal]

**Input**: [Requirements from previous step]

**Tool**: Skill("sub-{name}")

**Gate**: [Success criterion before proceeding]

**On Failure**: [Fallback behavior]

3. Quality Gate Validation

The main harness validates all outputs against 10 quality gates:

Universal Gates (U1-U6):

• U1: Source Count (≥3 sources, ≥1 academic/authoritative)
• U2: Disclosure Present (before recommendation)
• U3: Evidence Hierarchy (Tier labels per source)
• U4: Language Match (matches user preference)
• U5: Template Compliance (all sections present)
• U6: Claim Traceability (each claim cited or flagged)

Domain Gates (G1-G4):

• G1: Memory System Mapping (deficits → systems with evidence)
• G2: Research-Grounded Drills (spatial-cognition methods)
• G3: Red Flag Referral (pathological decline → medical)
• G4: Outcome Measures (measurable + graduated exposure)

Enforcement Logic:

For each gate in sequence:
    Check gate condition
    If failed and auto_fix available:
        Apply auto_fix
        Increment retry_count
        If retry_count  [mandatory notice before the recommendation]

## Recommendation / Conclusion
[verdict category, scenarios, key risks, evidence chain, remediation]

## Post-Execution Gate Checklist
[U1 pass U2 pass U3 pass U4 pass U5 pass U6 pass G1 pass G2 pass G3 pass G4 pass | Limitations: ...]

Verdict Schema

The final verdict must be exactly one of:

{
  "verdict": {
    "type": "string",
    "enum": [
      "Improvement Program Ready",
      "Conditional (compensatory focus)",
      "Medical Referral Needed",
      "Inconclusive"
    ],
    "required": true
  },
  "confidence": {
    "type": "string",
    "enum": ["high", "medium", "low"],
    "description": "Confidence level in the verdict"
  },
  "scenarios": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "probability": {"type": "number"},
        "outcome": {"type": "string"}
      }
    }
  }
}

Tool Definitions

The skill requires the following tools:

Core Tools

| Tool | Purpose | Usage Frequency | |------|---------|-----------------| | WebSearch | Fetch real-time domain data | Per analysis | | WebFetch | Retrieve authoritative documents | Per analysis | | Read | Read SECOND-KNOWLEDGE-BRAIN.md | Every invocation | | Write | Append knowledge entries | Weekly (automated) | | Bash | Run knowledge_updater.py | Scheduled | | Skill | Invoke sub-skills | 5x per analysis |

Tool Execution Handlers

WebSearch

# Pseudo-code for WebSearch invocation
results = WebSearch(
    query=constructed_search_query,
    domains=authoritative_sources,
    max_results=10,
    recency_filter="oneMonth"
)

WebFetch

# Pseudo-code for WebFetch invocation
document = WebFetch(
    url=authoritative_source_url,
    timeout=30.0,
    retries=3
)

Skill (Sub-Skill Invocation)

# Pseudo-code for sub-skill invocation
result = Skill(
    name="sub-core-analysis",
    input={
        "requirements": requirements_object,
        "evidence": evidence_bundle,
        "language": LANG
    }
)

Hooks System

Lifecycle Hooks

The skill implements hooks for lifecycle management:

Before Analysis

def before_analysis(input_data):
    """Hook called before analysis begins."""
    log_event("analysis_started", input_data)
    validate_input(input_data)
    detect_language(input_data)

After Sub-Skill

def after_sub_skill(step_name, result):
    """Hook called after each sub-skill completes."""
    log_event(f"{step_name}_completed", result)
    validate_step_output(step_name, result)
    update_shared_context(result)

Before Quality Gate

def before_quality_gate(gate_id, output):
    """Hook called before each quality gate check."""
    log_event(f"gate_{gate_id}_check", output)

After Quality Gate

def after_quality_gate(gate_id, result, auto_fixed):
    """Hook called after quality gate evaluation."""
    if auto_fixed:
        log_event(f"gate_{gate_id}_auto_fixed", result)
    if result.failed:
        log_event(f"gate_{gate_id}_failed", result.errors)

After Analysis

def after_analysis(final_output):
    """Hook called after analysis completes."""
    log_event("analysis_completed", final_output)
    record_metrics(final_output)
    emit_degradation_notice_if_needed(final_output)

State Synchronization

All sub-skills share a common context object:

class AnalysisContext:
    """Shared context across all sub-skills."""

    def __init__(self):
        self.requirements = {}
        self.evidence_bundle = {}
        self.analysis_results = {}
        self.knowledge_citations = []
        self.final_verdict = {}
        self.language = "en"
        self.degradation_level = 0
        self.gates_passed = []
        self.gates_failed = []
        self.limitations = []

    def update(self, key, value):
        """Update context with validation."""
        validate_context_update(key, value)
        setattr(self, key, value)
        emit_context_update_event(key, value)

Event Emission

Structured events are emitted for monitoring:

{
  "event_type": "step_completed",
  "timestamp": "2026-07-20T10:30:00Z",
  "step_name": "sub-core-analysis",
  "duration_ms": 1234,
  "success": true,
  "degradation_level": 0,
  "tokens_used": 8472
}

Validation

Input Validation

All inputs are validated against schemas:

def validate_input(input_data):
    """Validate input against schema."""
    schema = load_json_schema("input_schema.json")
    validator = jsonschema.Draft7Validator(schema)
    errors = list(validator.iter_errors(input_data))

    if errors:
        for error in errors:
            log_validation_error(error)
        raise ValidationError(f"Input validation failed: {errors}")

    return True

Output Validation

All outputs are validated against:

1. Template Compliance: All required sections present
2. Verdict Category: Must be one of 4 valid categories
3. Source Count: Minimum 3 sources, 1 academic
4. Disclosure Present: Must appear before recommendation
5. Language Consistency: Matches detected language

Schema Validation

JSON schemas are provided for:

• config/schema.json — Configuration validation
• assets/input_schema.json — Input contract validation
• assets/output_schema.json — Output contract validation
• assets/verdict_schema.json — Verdict structure validation

Error Handling

Error Types

| Error Type | Detection | Recovery | Retry Limit | |------------|-----------|----------|------------| | Source timeout | No response 30s | Retry alternate source | 3 | | Invalid input | Out-of-range/schema | Ask user to confirm | 2 | | Missing input | Field absent | Proceed with available + flag | N/A | | Stale reading | Timestamp old | Flag, request refresh | 1 | | Knowledge base miss | No matches | WebSearch gap-fill | 2 | | Conflicting actions | Mutually exclusive | Apply precedence | N/A | | Sub-skill failure | Exception raised | Degrade gracefully | 1 |

Error Recovery Pattern

try:
    result = execute_step(step_name, input_data)
except SubSkillError as e:
    degraded_result = handle_graceful_degradation(e, input_data)
    update_degradation_level(degraded_result.level)
    return degraded_result
except CriticalError as e:
    emit_critical_error(e)
    return error_output(e)

Performance Optimization

Context Window Management

The skill implements aggressive context management:

1. Progressive Loading: Load only necessary references per step
2. Content Pruning: Remove redundant information before output
3. Token Budgeting: Allocate token budget per step
4. Caching: Cache frequently accessed knowledge base sections

Token Optimization

Step 1 (Requirements):      ~500 tokens
Step 2 (Evidence):          ~2000 tokens (web fetches compressed)
Step 3 (Analysis):          ~3000 tokens
Step 4 (Knowledge):         ~1500 tokens (targeted queries)
Step 5 (Advisor):           ~2500 tokens
Quality Gates:              ~500 tokens
─────────────────────────────────────────
Total Budget:              ~10,000 tokens

Monitoring & Observability

Metrics Collected

• Execution Metrics: Duration per step, total duration
• Quality Metrics: Gates passed/failed, degradation level
• Resource Metrics: Tokens used, API calls made
• Error Metrics: Error types, retry counts, fallback usage

Logging Levels

| Level | Usage | Examples | |-------|-------|----------| | DEBUG | Detailed execution trace | Sub-skill inputs/outputs | | INFO | Normal operation | Steps completed, gates passed | | WARNING | Degraded operation | Fallbacks used, gates failed | | ERROR | Failures requiring attention | Critical errors, data unavailable |

Extensibility

Adding New Sub-Skills

To add a new sub-skill:

1. Create skills/sub-{name}.md with proper frontmatter
2. Define input/output contracts in the file
3. Add invocation step in main harness
4. Update quality gates if needed
5. Register in skill catalog

Adding New Quality Gates

To add a new quality gate:

1. Define gate in config/settings.py
2. Add check logic in main harness
3. Implement auto-fix if applicable
4. Update degradation level mapping
5. Test gate enforcement

Modifying Knowledge Sources

To modify knowledge sources:

1. Update KNOWLEDGE_CONFIG in tools/knowledge_updater.py
2. Update config/settings.json
3. Add new source to SECOND-KNOWLEDGE-BRAIN.md Section 4
4. Test crawl pipeline with --dry-run

Dependencies

Python Dependencies

requests>=2.31.0
feedparser>=6.0.10
python-dateutil>=2.8.2
jsonschema>=4.19.0
pydantic>=2.5.0

MCP Server Dependencies

• codegraph:* — Code intelligence and navigation
• plugin:supabase:supabase:* — Database operations (optional)
• web-reader:* — Web content fetching
• web-search:* — Search functionality

Version History

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-07-20 | Initial production release |

License

MIT License — see LICENSE file for details.

Contact & Support

For issues, questions, or contributions related to this skill, please refer to:

• Project Repository: D:\972026\181-spatial-navigation-memory-coach
• Documentation: README.md, PROJECT-detail.md
• Issue Tracking: See project CLAUDE.md for issue process

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/spatial-navigation-memory-coach-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.