From 1f91fdb308ca7831ee1db1f1b90c34fc12185fd1 Mon Sep 17 00:00:00 2001 From: Rusiru Rathmina Date: Mon, 26 Oct 2026 19:50:57 +0530 Subject: [PATCH] fix(drupal-skill): require readable and proportionate implementations --- skills/drupal-development/SKILL.md | 17 +++++++++++++++-- .../references/review-and-validation.md | 11 +++++++++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/skills/drupal-development/SKILL.md b/skills/drupal-development/SKILL.md index 4ff391f..2e75a37 100644 --- a/skills/drupal-development/SKILL.md +++ b/skills/drupal-development/SKILL.md @@ -5,7 +5,7 @@ description: Develop, debug, refactor, analyze, document, and review Drupal modu # Drupal Development -Develop, review, refactor, or analyze the requested scope against both the supplied Drupal practices and all applicable exported Sonar way rules. Preserve behavior and public contracts unless the requested change requires otherwise. +Develop, review, refactor, or analyze the requested scope against both the supplied Drupal practices and all applicable exported Sonar way rules. Preserve behavior and public contracts unless the requested change requires otherwise. Treat readability and simplicity as acceptance criteria alongside correctness and standards compliance. ## 0. State scope and clarification needs before work @@ -66,6 +66,19 @@ python /absolute/path/to/drupal-development/scripts/sonar_rules.py show php:S580 When a Sonar rule explicitly defines a Drupal-framework fallback, follow that Drupal-specific behavior for Drupal code. In this snapshot `php:S1781` uses uppercase `TRUE`, `FALSE`, and `NULL` in Drupal, and `php:S100` describes Drupal function naming when its default regex is unchanged. Confirm framework context and any configured parameter override; do not apply the generic default or silently disable a rule. Resolve any remaining material conflict using the guidance and report it with both sources. +## Keep the implementation easy to understand + +Apply these design constraints during development, refactoring, and review; use them alongside Drupal and Sonar requirements: + +- Choose the smallest coherent change that solves the current problem. Inspect nearby code and reuse existing services, utilities, and components before creating another implementation. +- Prefer explicit control flow, descriptive domain names, and one clear responsibility per function. Optimize for a maintainer understanding the code in one read, not for the fewest lines. Avoid dense expressions, clever chaining, excessive indirection, and deeply nested branches. +- Introduce a helper, class, interface, service, or configuration option only for a concrete current responsibility, meaningful reuse, an existing framework contract, or a necessary test boundary. Do not add factories, repositories, adapters, generic pipelines, or speculative extension points merely to anticipate future needs. Follow required Drupal dependency injection and plugin/service contracts without wrapping them in extra layers. +- Keep straightforward one-use logic inline when extraction would merely rename an expression or force the reader to jump between files. Extract when it makes a cohesive operation easier to understand; do not fragment a function solely to reduce its length or a metric. +- Keep validation at relevant trust boundaries and handle real failure cases. Avoid repeated checks for invariants the framework already guarantees, redundant fallback chains, swallowed exceptions, and invented defaults that conceal invalid state. Preserve security, access checks, escaping, cache metadata, and required contracts. +- Use comments and required Drupal documentation to explain intent, contracts, or a non-obvious constraint. Do not narrate obvious statements or add prose to compensate for confusing code; simplify the code first. +- Apply each mandatory standard and applicable Sonar rule using its full exceptions and Drupal fallback. Among compliant solutions, choose the clearest. Do not satisfy a metric with arbitrary helpers, hide findings through suppression, or weaken correctness/security to simplify code. Report a material unresolved conflict with evidence. +- Before finishing, remove unnecessary new abstractions, duplicate branches, unused options, and avoidable file changes. Be able to explain the purpose of each new layer in one sentence tied to the current requirement. For review-only work, report complexity as a maintainability recommendation unless there is evidence of a defect or a specific violated rule; do not rewrite automatically. + ## 3. Implement or review the change 1. Turn the applicable Drupal source sections and Sonar rule entries into a short task-specific checklist. Use [review and validation](references/review-and-validation.md) to check coverage across file types and Drupal integration points. Include secondary concerns across all affected languages. @@ -79,7 +92,7 @@ When a Sonar rule explicitly defines a Drupal-framework fallback, follow that Dr ## 4. Verify and report -1. Re-read the finished diff or reviewed scope against the applicable full Drupal standards and Sonar descriptions, including Drupal fallbacks and exceptions. Check every touched file type, documentation, supporting YAML, and integration boundary. Resolve conflicts through the compatibility workflow; disclose material deviations. +1. Re-read the finished diff for readability and unnecessary complexity using the [simplicity review](references/review-and-validation.md#review-simplicity), then check it against the applicable full Drupal standards and Sonar descriptions, including Drupal fallbacks and exceptions. Check every touched file type, documentation, supporting YAML, and integration boundary. Resolve conflicts through the compatibility workflow; disclose material deviations. 2. Run the project's existing relevant checks using its pinned dependencies and configuration. Discover commands from repository scripts and CI. Use the command patterns in [review and validation](references/review-and-validation.md) only after confirming their prerequisites. 3. Exercise changed behavior with appropriate tests or a targeted manual check. Include relevant failure/empty cases. Distinguish standards checks, syntax checks, behavior tests, and checks that could not run. 4. Inspect the final working tree for unintended edits or generated artifacts. Report what changed, what passed, and any specific remaining limitation. Never report a check as passing merely because a tool is absent or a command ran against zero files. diff --git a/skills/drupal-development/references/review-and-validation.md b/skills/drupal-development/references/review-and-validation.md index 7b47f08..2158bcd 100644 --- a/skills/drupal-development/references/review-and-validation.md +++ b/skills/drupal-development/references/review-and-validation.md @@ -4,6 +4,7 @@ - [Plan coverage](#plan-coverage) - [Check integration boundaries](#check-integration-boundaries) +- [Review simplicity](#review-simplicity) - [Choose project checks](#choose-project-checks) - [Use conditional command patterns](#use-conditional-command-patterns) - [Report evidence](#report-evidence) @@ -42,6 +43,16 @@ Treat these as implementation checks to complement the supplied style standard, - For UI changes, inspect the affected component in relevant states, viewport sizes, keyboard interaction, and LTR/RTL contexts as applicable. - Preserve data and public API compatibility during a style-only change. +## Review simplicity + +Read the changed code as its next maintainer. Follow the simplicity constraints in `SKILL.md` before accepting a standards-compliant result: + +- Trace the main behavior without unnecessary jumps between helpers or files. Replace dense expressions or deeply nested branches with clear steps when that improves understanding. +- Identify the current need for each new class, interface, helper, service, option, and dependency. Remove speculative layers and reuse an existing project facility where appropriate. Keep framework-required boundaries and abstractions with a concrete responsibility. +- Check that extraction names a meaningful operation rather than disguising complexity or satisfying a metric. Allow limited local repetition when sharing would couple unrelated behavior; extract genuinely shared behavior with a clear owner. +- Preserve behavior, security, access/cache semantics, error visibility, and test coverage while simplifying. Never equate fewer lines or files with better design automatically. +- In code reviews, explain the specific maintenance cost and offer the smallest useful correction. Distinguish a readability recommendation from a confirmed bug or sourced standards violation. + ## Choose project checks Read Composer/package scripts, CI jobs, installed binaries, lint configuration, ignore patterns, and existing test instructions. Prefer the repository's own commands. Run checks against changed custom code and relevant integration points; include dependencies only when the change requires it.