skill-ls/PLAN.md

Project Hardening Plan

This document outlines the identified fragilities in the skillls project and the planned architectural improvements to transform it from a functional prototype into a robust, production-ready Language Server.

1. Grammar-Logic Decoupling

Problem: The SkillParser relies on hardcoded string literals (e/g., "function_definition") to identify symbols. Changes in the underlying tree-sitter-skill grammar will cause silent failures in the Outline view. Goal: Create a stable contract between the grammar and the parser. Proposed Actions:

• Implement a shared constants module or configuration file that defines significant node types.
• (Long-term) Explore using Tree-sitter Queries (Query API) to match patterns instead of manual type checking, making the parser less dependent on specific node names and more focused on structural patterns.

2. Iterative AST Traversal

Problem: The current recursive traversal in _traverse_tree is susceptible to RecursionError on deeply nested files. Goal: Ensure the server can handle arbitrarily deep syntax trees without crashing. Proposed Actions:

• Refactor SkillParser._traverse_tree to use an iterative approach (using a stack/deque) instead of recursion.

s3. Single Source of Truth for Errors

Problem: The project is in a transitional state where error management is split between the new SkillParser diagnostics and the legacy server.errs dictionary in main.py. Goal: Unify error reporting into a single, streamlined pipeline. Proposed Actions:

• Complete the refactor of skillls/main.py.
• Remove the errs dictionary from SkillLanguageServer.
• Decommission and delete deprecated files: skillls/checker.py and unused parts of skillls/helpers.py.

5. Test Suite Strengthening

Problem: While core logic is tested, the LSP lifecycle and complex parsing edge cases lack specific unit test coverage. Goal: Achieve high-confidence verification of the LSP server's behavior and parser robustness. Proposed Actions:

• Implement tests/test_server.py to verify LSP lifecycle events (didOpen, didChange) and diagnostic publishing logic.
• Expand tests/test_helpers.py with specialized unit tests for the find_scopes regex and brace-tracking logic.
• Harden tests/test_parser.py by implementing deterministic symbol extraction verification instead of existence checks.