Repository Analysis

The goal is to discover the project's real architecture before writing rules. Do not start from generic spec templates and fill blanks. Start from the code, then let the spec structure follow.

Analysis Order

Read the existing .trellis/spec/ tree and note which files are templates, outdated, or already project-specific.
Inspect package manifests, build scripts, workspace config, and top-level documentation to identify packages and runtime layers.
Use GitNexus for execution flows, module clusters, dependency hubs, and impact-sensitive areas.
Use ABCoder or language-native tooling for exact signatures, types, class boundaries, and implementation examples.
Read representative source and test files directly before turning any finding into a spec rule.

What To Capture

Area	Questions
Package boundaries	What does each package own? What imports cross boundaries?
Runtime layers	Which code is CLI, backend, frontend, worker, shared library, test-only, or tooling?
Core abstractions	Which types, services, stores, commands, routes, or adapters define the system shape?
Data flow	Where does user input enter, how is it validated, and where does state persist?
Error handling	How are failures represented, logged, surfaced, and tested?
Configuration	Where do defaults, environment config, generated files, and templates live?
Tests	Which test styles are trusted examples for new work?

GitNexus Usage

Start broad, then inspect specific symbols:

gitnexus_query({query: "CLI command execution flow"})
gitnexus_query({query: "template generation and migration"})
gitnexus_context({name: "SymbolName"})
gitnexus_cypher({query: "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 30"})

Use GitNexus results to find important files and flows. Do not quote graph output as the final authority until you have checked the relevant source files.

ABCoder Usage

Use ABCoder when the spec needs exact code shapes:

list_repos()
get_repo_structure({repo_name: "package-name"})
get_file_structure({repo_name: "package-name", file_path: "src/example.ts"})
get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "SymbolName"}]})

ABCoder is most valuable for documenting constructor patterns, function signatures, type contracts, and reference chains.

Analysis Notes

Keep short notes while analyzing. The notes should include:

Package or layer name.
Files that define the local pattern.
Rules the spec should teach.
Anti-patterns found in old code, comments, tests, or migration paths.
Spec files that should be created, deleted, renamed, or merged.

2.7 KiB Raw Blame History