Skip to main content

Skyhawk Site Modernization Roadmap

Skyhawk Site Modernization Roadmap

READ THIS FIRST: AI / Maintainer Operating Contract

Mission: Deliver verified, maintainable changes to this specific Skyhawk Drupal site with the fewest practical iterations. Plausible code is not success. Verified working behavior is success.

Read this page in full before coding, then read every reference page relevant to the task. Do not reconstruct facts from memory, guess at the current state, or rediscover settled decisions.

Required external behavior: known state → applicable references → agreed task → inspection → implementation → lint/validation → execution → evidence capture → verification → reference update → next state. The model may be probabilistic internally; the workflow must be deterministic.

1. Mandatory Workflow

  1. Reference first. Before each material coding step, read this page and the applicable subject-specific reference pages. Current reference pages outrank conversational inference when they contain an applicable path, architecture decision, established mechanism, completed decision, or known state.
  2. State before action. Inspect the relevant file, configuration, route, View, module, theme, template, field, log, or rendered output before changing anything. Never code against an imagined state.
  3. Discuss narrowly and agree first. Do not expand scope, create side projects, or infer new goals. Ask before writing code unless Gene has explicitly authorized coding.
  4. Search before creating. Search the actual codebase and Drupal configuration, including all custom modules and relevant theme/configuration locations, before adding a mechanism.
  5. One complete block per agreed step. Include pre-flight checks, backup/rollback when consequential, the modification, lint/validation, execution, evidence capture, and targeted verification. Then stop for actual results.
  6. One change set, one verification target. Do not mix unrelated changes. Each change must have a defined expected result and a test that proves or disproves it.
  7. Close branches. Every failed test must narrow the search space. Record what the evidence eliminated. Do not repeat the same failed test or revive a disproved theory unless new evidence reopens it.
  8. Proceed linearly. Do not redo, redesign, move, replace, or reopen completed verified work merely because another approach exists.

2. Drupal Architecture: Let Drupal Be Drupal

Drupal is the platform. Conform to Drupal before customizing Drupal. Access to enormous amounts of source code does not make custom code the preferred answer. On skyhawk.org, sophistication includes knowing when not to write code.

  1. Preference order: Drupal core behavior/configuration first; established contributed modules/themes second; Views wherever Views can reasonably solve a listing, query, grid, filter, or administrative-report problem; existing Skyhawk custom mechanisms next; new custom code only when the preceding choices cannot cleanly meet the requirement.
  2. Views rule: Do not hand-code entity queries, listing pages, grids, filters, or content reports when Views can reasonably provide them.
  3. Core and contrib remain pristine. Never implement Skyhawk-specific behavior by editing /core, /modules/contrib, or /themes/contrib. Drupal updates must not erase or collide with site-specific work.
  4. Use established custom locations. Genuinely site-specific integration belongs in the existing skyhawk_site_fixes custom module unless an established mechanism already owns the behavior. Do not create another custom module merely to isolate a small fix.
  5. One global stylesheet. Global site behavior belongs in skyhawk_site_fixes/css/skyhawk-global.css. Do not create another global stylesheet. Do not turn page-specific exceptions into global rules.
  6. Preserve established architecture. Do not recreate retired CSS, retired themes, superseded implementations, or duplicate mechanisms.
  7. Legacy content is preserved unless there is a practical reason and explicit agreement to modernize it.

3. Clean Editing: Know and Replace, Never Guess and Append

  1. Search before edit. Before changing a selector, hook, route, service, template, View, formatter, configuration key, or related mechanism, locate the relevant existing implementation and references.
  2. No cumulative patching. Inspect and understand the current logical block, then replace that complete logical block with the final version whenever practical. Do not stack corrective fragments on top of earlier corrective fragments.
  3. CSS sediment is a failure state. Do not append one rule to reverse another, then a third to reverse the reversal. Locate the owning block and replace it cleanly.
  4. Do not blindly append to PHP, JS, Twig, YAML, CSS, or configuration. Know the current contents and ownership first.

4. Code Quality Gate

Code is not ready merely because an AI generated it. Before presenting executable code, validate syntax, paths, quoting, environment assumptions, destructive scope, rollback, and the verification method.

  • PHP: php -l where applicable.
  • Bash: bash -n where applicable.
  • JSON: parse with available tooling such as jq or python -m json.tool.
  • YAML and PowerShell: perform practical parser/syntax validation when tooling is available.
  • Drupal: use the appropriate Drush/configuration/cache action plus a targeted functional check.
  • CSS/JS/Twig: use available static/syntax checks, then verify the actual rendered or loaded result.

Do not demand imaginary tooling. Use the strongest practical validation available.

5. Evidence and Verification

  1. No success language without proof. Do not claim fixed, working, loaded, deleted, redirected, clean, installed, or confirmed unless the evidence directly proves that claim.
  2. If execution occurred but verification has not, say changed, attempted, or not yet verified.
  3. Separate diagnosis from modification. When the cause is uncertain, begin with a read-only audit.
  4. Back up before consequential changes and verify afterward. Read-only diagnostics do not need ceremonial backups.
  5. Confirmed live docroot: /home/darwus/drupalbeta/web. Do not use /home/darwus/public_html/drupalbeta or variants.
  6. Confirmed site error log: /home/darwus/drupalbeta/web/error_log. Before trusting any log, prove it belongs to the site/domain being worked on.
  7. To prove a JavaScript library is loading, inspect actual rendered script src output or the aggregated bundle it references. Grepping rendered HTML for a Drupal library machine name proves nothing.
  8. Any route showing per-request or token-gated state must trigger Drupal's page_cache_kill_switch in the form/controller so stale page cache cannot silently serve old state.

6. Standard AI Debug Channel

The debug channel exists to eliminate routine copy/paste between Termux, Windows, Mac, mobile devices, and the AI.

Authoritative current-report URL: https://skyhawk.org/downloads/chatgpt-debug-latest.txt.

The authoritative latest file contains the complete current report, not merely a pointer. Each diagnostic run also creates an immutable archive report named with a unique Report-ID, such as /downloads/chatgpt-debug-20260824T164135Z-698130.txt. The immutable archive is retained as historical execution evidence, but the AI normally reads the fixed latest URL directly.

Publish atomically. Build the complete report in a temporary file. After the report is finished, move it into the immutable archive filename, then copy that completed archive to a temporary latest filename and atomically move the temporary latest file into /downloads/chatgpt-debug-latest.txt. Never stream a still-changing report directly into either public filename.

The complete report must begin with:

SKYHAWK AI DEBUG REPORT
Task: <plain-language task>
Generated: <timestamp with timezone>
Report-ID: <unique timestamp/nonce>
Archive-URL: https://skyhawk.org/downloads/chatgpt-debug-<Report-ID>.txt
Host: <hostname>
Working directory: <pwd>
Drupal root: /home/darwus/drupalbeta/web

===== PRE-FLIGHT =====
...
===== ACTION =====
...
===== LINT / VALIDATION =====
...
===== VERIFICATION =====
...
===== ERRORS =====
...
===== END =====

Freshness is mandatory. After Gene confirms that a report was updated, the AI reads chatgpt-debug-latest.txt and validates Task:, Generated:, Report-ID:, host, working directory, and Drupal root against the current work before relying on it.

If the first retrieval is stale, that is a retrieval-layer failure, not evidence that the A2 command failed. Retry the known latest URL with a cache-busting query value when the retrieval tool permits it. Do not report server failure merely because an intermediary served an older object.

Do not ask Gene to paste terminal output merely because retrieval is stale. Manual copy/paste is a fallback only when the fixed latest-report channel cannot be read after reasonable fresh-retrieval attempts.

Never place secrets in public debug reports. Do not include passwords, private keys, session cookies, API keys, active upload tokens, personal data, database credentials, or other sensitive material. Redact before publication.

Capture enough evidence to determine the next state, not thousands of irrelevant lines. Use the older A2-to-Windows report-transfer workflow only when Gene actually needs a local file.

7. Living Reference System

  1. Reference continuously, update immediately. The /blade/ reference pages are the persistent operating state of skyhawk.org, not historical notes.
  2. Code and documentation are one transaction. When Gene and the AI agree during a session to a material architecture decision, path, procedure, convention, completed feature, or changed system state, update the appropriate reference page during that same work session as part of the change.
  3. Do not postpone documentation until the end. If direction changes during coding, update the reference page as soon as the new direction is settled so obsolete instructions do not poison the next step or next session.
  4. One source of truth per subject. Keep detailed facts on the appropriate subject page and link to them rather than maintaining conflicting copies.
  5. Conversation is working memory; reference pages are institutional memory. Do not rely on conversational history when a durable reference exists.

8. Existing Binding Site Rules

  1. Respect limited-answer requests. If Gene requests Yes/No only, answer Yes or No.
  2. Use the word "hero" only for someone who did something heroic.
  3. No Drupal messenger()/status popups for Skyhawk custom forms. Form/action results render inline using the established PageMessageTrait pattern in skyhawk_site_fixes/src/Traits. The known skyhawk_gallery/PhotoContributionForm.php exception is not a pattern to copy and is not authorization for a side project.
  4. Downloaded scripts are ZIP files rather than loose plain-text script downloads.
  5. For squadron work, follow the current squadron modernization prototype and lessons rather than one-node patches.

9. Reference Pages

10. Continuity Test

A future AI agent or maintainer should be able to read this page, follow the applicable references, establish the current state without rediscovering settled facts, make the smallest correct update-safe change, validate it, capture evidence, verify it, update the durable reference state, and continue without reopening completed work.

Operating shorthand: reference → inspect → agree → implement → lint → execute → capture → verify → update reference → next task.