Add Terraform module workflow skills for story, requirements, code generation, and docs

[emrousselle]

This PR adds a new set of Terraform module-generation skills that define an end-to-end authoring workflow from story creation to implementation and documentation.

What changed:

• Addedterraform-module-story-builderskill to structure IaC user stories using As a / I want / so that format.
• Added terraform-module-acceptance-criteria-builder skill to convert stories into testable EARS requirements.
• Added supporting references for acceptance criteria:
  • terraform variable design guidance
  • terraform output design guidance
• Added terraform-module-code-generator skill to generate module implementation files from specification inputs.
• Added terraform-module-documentation-writer skill to generate and maintain module README content and required examples without external CLI dependencies.

Why:

• Standardizes how module requirements are captured and traced.
• Improves consistency between requirements, implementation, and docs.
• Provides a repeatable, skill-driven workflow for Terraform module delivery.

[github-actions]

Tessl Skill Review Results

Skill	Status	Review Score	Change
terraform/module-generation/skills/terraform-module-acceptance-criteria-builder	✅ PASSED	79%
terraform/module-generation/skills/terraform-module-code-generator	✅ PASSED	71%
terraform/module-generation/skills/terraform-module-documentation-writer	✅ PASSED	71%
terraform/module-generation/skills/terraform-module-story-builder	✅ PASSED	88%

---

Detailed Review

terraform/module-generation/skills/terraform-module-acceptance-criteria-builder — 79% (PASSED)

  Description: 75%
    specificity: 2/3 - The description names the domain (Terraform modules, infrastructure-as-code) and the core action (turn high-level needs into testable requirements using EARS notation), but it doesn't list multiple concrete actions—it's essentially one action described at a high level.
    trigger_term_quality: 2/3 - Includes relevant keywords like 'Terraform modules', 'infrastructure-as-code', 'EARS notation', and 'requirements', but misses common user variations (e.g., 'IaC requirements', 'requirement specification', 'terraform requirements', 'acceptance criteria'). Some terms like 'EARS notation' are niche jargon users may not naturally use.
    completeness: 2/3 - The 'what' is reasonably clear (convert high-level needs into EARS requirements), but the 'when' is only implied through the opening 'Use this skill to...' rather than providing explicit trigger conditions like 'Use when the user asks for...' with specific scenarios.
    distinctiveness_conflict_risk: 3/3 - The combination of EARS notation, Terraform/IaC context, and the mention of companion IaC story skills creates a very specific niche that is unlikely to conflict with other skills.

    Assessment: The description identifies a clear niche (EARS requirements for Terraform/IaC) which makes it distinctive, but it lacks explicit trigger guidance ('Use when...') and could be more specific about the concrete actions it performs. The use of second person ('Use this skill') slightly detracts, and the description would benefit from listing specific trigger scenarios and more natural user keywords.

  Content: 83%
    conciseness: 2/3 - The skill is reasonably well-structured but includes some redundancy and verbosity. The EARS pattern quick reference is useful, but the variable extraction and output extraction tables (steps 10-11) repeat information that could be more tightly integrated. Some instructions like 'mentally check' and general advice about staying concise are meta-commentary that adds tokens without adding value for Claude.
    actionability: 3/3 - The skill provides highly concrete, actionable guidance: specific EARS pattern templates with exact syntax, a clear output format with markdown examples, variable inference rules mapped to naming patterns, and a step-by-step process. The output template is copy-paste ready and the pattern-to-variable mapping table is directly executable.
    workflow_clarity: 3/3 - The 11-step process is clearly sequenced from input normalization through scope clarification, behaviour identification, pattern mapping, requirement writing, ID assignment, output formatting, testability checking, and variable/output extraction. Step 8's testability check serves as a validation checkpoint. For a non-destructive requirements-generation task, this level of workflow clarity is excellent.
    progressive_disclosure: 2/3 - The skill references two external files (references/terraform-variables.md and references/terraform-outputs.md) which is good progressive disclosure design, but no bundle files are provided so these references are broken. The main content is somewhat monolithic — the variable extraction and output extraction sections could potentially be split into reference files. The overall organization within the single file is decent but long.

    Assessment: This is a well-structured, highly actionable skill that provides clear EARS pattern templates and a thorough step-by-step workflow for deriving testable IaC requirements. Its main weaknesses are moderate verbosity (some sections could be tightened) and references to bundle files that don't exist, undermining progressive disclosure. The output format template and pattern-mapping tables are strong assets that make this skill immediately usable.

Suggestions:

• Add an explicit 'Use when...' clause with trigger scenarios, e.g., 'Use when the user asks to write requirements for Terraform modules, define acceptance criteria for IaC, or convert infrastructure needs into structured EARS requirements.'
• Include more natural trigger terms users might say, such as 'acceptance criteria', 'requirement specification', 'IaC requirements', 'terraform testing requirements', or 'infrastructure requirements'.
• List more specific concrete actions beyond just 'turn needs into requirements', e.g., 'Generates EARS-formatted requirements (ubiquitous, event-driven, state-driven, optional-feature, unwanted-behavior patterns) from high-level Terraform module descriptions.'
• Provide the referenced bundle files (references/terraform-variables.md and references/terraform-outputs.md) or remove the references to avoid broken links.
• Tighten steps 10 and 11 — the variable and output extraction tables partially duplicate guidance already implicit in step 5 and the output format template; consider consolidating.

terraform/module-generation/skills/terraform-module-code-generator — 71% (PASSED)

  Description: 67%
    specificity: 2/3 - Names the domain (Terraform module implementation) and describes the action (generate files from a specification document), but doesn't list multiple concrete actions like creating variables.tf, outputs.tf, main.tf, or specific Terraform constructs.
    trigger_term_quality: 2/3 - Includes relevant terms like 'Terraform', 'module', 'EARS requirements', and 'user story', but misses common variations users might say such as 'infrastructure as code', 'IaC', '.tf files', 'HCL', or 'terraform plan'.
    completeness: 1/3 - Describes what it does (generate Terraform module files from a spec), but has no explicit 'Use when...' clause or trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'when' is entirely absent, warranting a 1.
    distinctiveness_conflict_risk: 3/3 - The combination of Terraform modules, EARS requirements, and module specification documents creates a very specific niche that is unlikely to conflict with other skills.

    Assessment: The description identifies a clear and distinctive niche (Terraform module generation from EARS requirements), which is its strongest aspect. However, it lacks an explicit 'Use when...' clause and could benefit from more specific concrete actions and natural trigger terms that users would employ when requesting this type of work.

  Content: 75%
    conciseness: 2/3 - The content is reasonably efficient but includes some unnecessary elaboration. Steps like 'Step 5: Generate versions.tf' and 'Step 6: Ensure generated code quality baseline' contain guidance Claude already knows (descriptive names, complete variable descriptions). The pattern mapping guidance and workflow steps could be tighter.
    actionability: 2/3 - The skill provides a structured workflow and one concrete HCL example with traceability comments, but most steps are descriptive rather than executable. There are no complete code templates, no example specification input, and no example of a fully generated module output. The pattern mapping guidance is helpful but abstract.
    workflow_clarity: 2/3 - Steps are clearly sequenced (1-7) and logically ordered, but there are no validation checkpoints. For a code generation task that produces multiple files, there's no verification step (e.g., 'run terraform validate' or 'check all REQ-* IDs are covered'). Missing feedback loops for ensuring completeness caps this at 2.
    progressive_disclosure: 3/3 - For a standalone skill with no bundle files, the content is well-organized into clear sections (Input, Implementation workflow with numbered steps, Output expectations). The length is appropriate and doesn't need external references. Sections are logically separated and easy to navigate.

    Assessment: This skill provides a reasonable workflow structure for generating Terraform modules from specifications, with good organization and a useful EARS-to-code pattern mapping. However, it lacks concrete executable examples (only one small HCL snippet), has no validation/verification steps in the workflow, and includes some guidance that Claude already knows about Terraform conventions. Adding a complete input/output example and a validation checkpoint would significantly improve it.

Suggestions:

• Add a 'Use when...' clause such as 'Use when the user asks to implement a Terraform module from a specification, or when working with EARS requirements for infrastructure as code.'
• Include more natural trigger terms users might say, such as 'infrastructure as code', 'IaC', 'HCL', '.tf files', 'terraform module scaffolding'.
• List more specific concrete actions, e.g., 'Generates main.tf, variables.tf, outputs.tf, and provider configurations based on EARS-format requirements and user stories.'
• Add a complete example showing a small specification input and the expected generated file outputs (at least a partial main.tf and variables.tf) to make the skill truly actionable.
• Add a validation step after file generation, such as running 'terraform validate' or checking that all REQ-* IDs from the specification appear in generated code comments.
• Remove Step 6 (quality baseline) or reduce it to a single line — Claude already knows Terraform style conventions; listing 'descriptive names' and 'complete variable descriptions' wastes tokens.

terraform/module-generation/skills/terraform-module-documentation-writer — 71% (PASSED)

  Description: 83%
    specificity: 2/3 - Names the domain (Terraform module README.md documentation) and mentions some actions ('generate and maintain'), but doesn't list multiple specific concrete actions like 'create input/output tables, document examples, describe resource dependencies'.
    trigger_term_quality: 3/3 - Includes strong natural keywords users would say: 'README.md', 'Terraform modules', 'terraform-docs', 'HashiCorp', 'module documentation', 'module structure'. These cover common variations of how users would phrase requests in this domain.
    completeness: 2/3 - Clearly answers 'what does this do' (generate/maintain README.md for Terraform modules) but lacks an explicit 'Use when...' clause. The when is only implied by the description of capabilities, which per the rubric caps completeness at 2.
    distinctiveness_conflict_risk: 3/3 - Very clearly scoped to Terraform module README documentation specifically, with distinct triggers like 'Terraform modules', 'HashiCorp', and 'terraform-docs'. Unlikely to conflict with general documentation or general Terraform skills.

    Assessment: The description is well-scoped to a clear niche (Terraform module README documentation) with good trigger terms that users would naturally use. Its main weaknesses are the lack of an explicit 'Use when...' clause and the absence of more specific concrete actions beyond 'generate and maintain'. Adding explicit trigger guidance and enumerating specific documentation tasks would elevate this description.

  Content: 58%
    conciseness: 1/3 - The skill is extremely verbose at ~350+ lines. It over-explains concepts Claude already knows (how to parse HCL text, what a root vs nested module is, what semantic versioning means), includes extensive meta-commentary about robustness practices, and repeats itself across sections (e.g., the no-external-tools constraint is stated multiple times). Much of this could be condensed to under 100 lines without losing actionable content.
    actionability: 2/3 - The skill provides a concrete README template skeleton with table structures and a clear example output format, which is good. However, the actual parsing instructions are described procedurally rather than with executable code, and the usage examples are generic placeholders rather than fully fleshed-out demonstrations. The workflow steps describe what to do conceptually but lack concrete implementation details for the parsing logic.
    workflow_clarity: 3/3 - The 9-step workflow is clearly sequenced with explicit ordering, each step has a defined purpose, and there are validation checkpoints (e.g., Step 5 compares existing README against .tf files, Step 6 has a 'completion gate' requiring examples before finalizing). The handling of conflicts between README and .tf files includes a clear resolution strategy treating .tf as authoritative.
    progressive_disclosure: 1/3 - The entire skill is a monolithic wall of text with no references to supporting files despite being long enough to warrant splitting. The detailed README template, parsing heuristics, Mermaid diagram examples, and output format specifications could all be separate referenced files. No bundle files exist to support this content, and everything is inlined into a single massive document.

    Assessment: The skill demonstrates strong workflow clarity with a well-sequenced 9-step process and explicit validation gates, but is severely undermined by excessive verbosity—it explains many concepts Claude already understands (HCL parsing, semantic versioning, module classification) and repeats constraints multiple times. The content would benefit enormously from being condensed to its essential novel instructions and split across supporting reference files for the template skeleton, parsing rules, and examples.

Suggestions:

• Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create, update, or review README.md files for Terraform modules, or mentions terraform-docs, module documentation, or HCL variable/output documentation.'
• List more specific concrete actions, e.g., 'Generate input/output variable tables, document usage examples, describe provider requirements, and list submodule dependencies.'
• Reduce content by at least 50% by removing explanations of concepts Claude already knows (what semantic versioning is, what root vs nested modules are, how to parse text) and eliminating repeated constraints (the no-external-tools rule appears 3+ times).
• Extract the README template skeleton, Mermaid diagram examples, and output format specification into separate referenced files (e.g., TEMPLATE.md, EXAMPLES.md) to improve progressive disclosure.
• Replace the procedural description of HCL parsing in Step 2 with a concrete, executable code example or a more concise specification of the extraction rules.
• Consolidate the 'When to use / When not to use' section and the 'Robustness and safety practices' section into briefer bullet points, as much of this content restates obvious constraints.

terraform/module-generation/skills/terraform-module-story-builder — 88% (PASSED)

  Description: 83%
    specificity: 2/3 - Names the domain (Agile user stories for IaC/Terraform) and some actions ('write and refine'), but doesn't list multiple concrete actions like formatting acceptance criteria, defining personas, structuring story templates, etc.
    trigger_term_quality: 3/3 - Includes strong natural keywords users would say: 'Agile', 'user stories', 'infrastructure-as-code', 'Terraform modules', 'platform', 'security', 'reusable modules', 'personas', 'goals'. These cover common variations of how users would describe this need.
    completeness: 2/3 - The 'what' is reasonably clear (write and refine Agile user stories for IaC/Terraform), but there is no explicit 'Use when...' clause or equivalent trigger guidance. The when is only implied by the description of the domain.
    distinctiveness_conflict_risk: 3/3 - The combination of Agile user stories specifically for infrastructure-as-code and Terraform modules is a clear niche. It's unlikely to conflict with general Agile skills or general Terraform skills due to the specific intersection.

    Assessment: The description identifies a clear and distinctive niche—Agile user stories for IaC/Terraform—with good natural trigger terms. However, it lacks an explicit 'Use when...' clause and could be more specific about the concrete actions it performs beyond 'write and refine'. Adding explicit trigger guidance and more granular capabilities would strengthen it.

  Content: 92%
    conciseness: 2/3 - The skill is reasonably well-structured but includes some unnecessary explanation that Claude would already know (e.g., explaining what INVEST stands for, explaining that 'systems are not users'). The anti-patterns section and some of the core principles could be tightened. However, it's not egregiously verbose.
    actionability: 3/3 - The skill provides a concrete template, specific examples of good and bad story formulations, a clear output format with markdown structure, and explicit rules for each component (persona, capability, value). This is copy-paste ready guidance that Claude can directly follow.
    workflow_clarity: 3/3 - The 6-step process is clearly sequenced: clarify context → draft story → adapt for Terraform/IaC → output in specific format → split if too large → check for anti-patterns. For a non-destructive, conversational skill like user story writing, this workflow is well-structured with appropriate checkpoints (clarifying questions, anti-pattern review).
    progressive_disclosure: 3/3 - For a standalone skill with no bundle files, the content is well-organized into clear sections (Purpose, When to use, Core principles, Instructions) with appropriate depth. The content length is reasonable and doesn't need to be split into separate files. Sections are well-signaled with headers and numbered steps.

    Assessment: This is a well-structured, actionable skill for writing infrastructure user stories. Its main strength is the clear workflow, concrete examples contrasting good vs. bad formulations, and a specific output template. The primary weakness is moderate verbosity—some principles and explanations could be tightened since Claude already understands concepts like INVEST, what constitutes a good user story, and that systems aren't users.

Suggestions:

• Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to write, review, or refine user stories for Terraform modules, infrastructure-as-code projects, or platform engineering work.'
• List more specific concrete actions, e.g., 'Drafts acceptance criteria, structures story format with persona/goal/value, splits epics into stories, reviews stories for clarity and testability.'
• Trim the 'Core principles' section by removing explanations Claude already knows (e.g., the INVEST acronym expansion) and consolidating the anti-pattern guidance into the principles rather than having a separate section.

---

Checks: frontmatter validity, required fields, body structure, examples, line count.
Review score is informational — not used for pass/fail gating.