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.

4. Dependency Management Stabilization

Problem: The dependency on a private SSH Git URL for tree-sitter-skill introduces external failure points into the build pipeline. Goal: Stabilize the build environment. Proposed Actions:

• Evaluate the feasibility of publishing tree-sitter-skill to a private PyPI registry or a more accessible artifact repository.
• Implement a fallback/vendoring strategy for critical grammar components if possible.