env-discovery

Environment Discovery — Fleet Intelligence

Discover the environment structure by navigating tags, do not enumerate individual resources.

Workflow

1. Confirm the scan target

• Confirm the account ID (default <account-id>, read from environment.md)
• Confirm the region scope (by default, scan all regions listed in environment.md)

2. Run the scan

• Run the scripts/discover-account.sh <account-id> <region>
• script; the three phases execute independently: tag discovery → resource aggregation → alarm status
• Output JSON to stdout, and also update account.yaml and account.md under environments/

3. Terminal summary output

• Parse the JSON output by the script and render the terminal summary
• Include: resource counts per service, current alarms, anomaly markers
• Every conclusion in the report must be traceable to the JSON data from this scan, and it is forbidden to carry over unverified information from old account.yaml comments, historical reports, or memory

3.1 Compare with the previous scan (optional)

• Read account.yaml to get the previous service_catalog, and diff it against the current JSON
• The comparison scope is limited tothe three phases covered by this script(tag / resource aggregation / alarm)
• Comments, log_sources, etc. in account.yamlare outside the script's scan scopeand must not be cited as comparison conclusions—if such information needs to be reported, it must be separately queried and verified
• When changes are found, mark them as "added / disappeared / count changed" with specific data

4. Two query modes

Mode 1: Global overview ("How is the environment?")

1. Read environments//account.yaml to get the service catalog
2. Query CloudWatch Alarms in ALARM state → classify them into services by alarm_prefix
3. Output: health summary per service + abnormal alarms

Mode 2: Targeted drill-down ("How is the trading engine's DB?")

1. Find the tag and resource_types from the service catalog
2. Use the tag to filter and query CloudWatch metrics for the target resources
   • RDS: CPUUtilization, FreeableMemory, ReplicaLag
   • EC2: CPUUtilization, StatusCheckFailed
   • EKS: pod restart count, node status
3. Return only metric anomalies or resource details the user cares about

Query reference

For specific AWS CLI commands and interpretation points for each service, see references/service-checklist.md. Do not write your own query commands—use the commands verified in the checklist.

Automation Boundary

auto-safe

• All describe / list / get queries
• resourcegroupstaggingapi calls
• cloudwatch describe-alarms
• Generate report files

human-required

• None (this skill is purely read-only)

Gotchas

• resourcegroupstaggingapi In the ARN returned by ec2 covers all resources such as instance/vpc/subnet/sg/nat/igw, etc. The subtype must be extracted from the 6th segment of the ARN (e.g., ec2:instance), otherwise it will falsely report "19 EC2 instances" when they are actually network resources
• When inferring primary_key from tags, exclude k8s system tags (those whose key contains . or / , such as alpha.eksctl.io/xxx）
• Personal/experimental accounts may not have business-level tags (such as service），Project or Name may be the closest substitute
• Historical comments in account.yaml are not real-time data. The script only produces three types of data: tag/resource aggregation/alarm; the log_sources, handwritten comments, etc. in account.yaml are maintained by other processes or manually. Inspection reports must not treat these as conclusions of this scan. Before citing them, the current state must be verified with the CLI
• After scanning, clean up outdated comments in account.yaml. Resolved issues are marked with the resolution time; do not leave unverified issues around—they will mislead the next scan.