fix: address PR review feedback for aws-observability plugin

- Replace wildcard IAM permissions with least-privilege read-only actions
  in SKILL.md (Copilot review comment awslabs#5)
- Add missing `| limit 100` to Performance Analysis query example in
  SKILL.md (Copilot review comment awslabs#4)
- Fix DynamoDB Throttles alarm pattern to use ReadThrottleEvents /
  WriteThrottleEvents instead of UserErrors (Copilot review comment awslabs#3)
- Fix lookup_events example to use 90-day window matching API limits
  (Copilot review comment awslabs#1)
- Remove orphaned pattern numbering ("Pattern 2/3/4" with no Pattern 1)
  in security-auditing.md (Copilot review comment awslabs#2)
- Replace all "steering file" terminology with "reference" across all 8
  reference files for consistency with plugin conventions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: theagenticguy

plugins/aws-observability/skills/aws-observability/SKILL.md

@@ -12,12 +12,12 @@ Comprehensive AWS observability platform combining monitoring, troubleshooting,
 1. **AWS CLI configured** with credentials (`aws configure` or `~/.aws/credentials`)
 2. **Python 3.10+** and `uv` installed
 3. **Application Signals enabled** in your AWS account when applicable
-4. **Required AWS Permissions**:
-   - `cloudwatch:*` for CloudWatch Metrics and Alarms
-   - `logs:*` for CloudWatch Logs operations
-   - `xray:*` for distributed tracing
-   - `cloudtrail:*` for CloudTrail queries
-   - `application-signals:*` for Application Signals
+4. **Required AWS Permissions** (read-only, least-privilege):
+   - **CloudWatch Metrics & Alarms**: `cloudwatch:GetMetricData`, `cloudwatch:GetMetricStatistics`, `cloudwatch:ListMetrics`, `cloudwatch:DescribeAlarms`, `cloudwatch:DescribeAlarmsForMetric`, `cloudwatch:DescribeAlarmHistory`, `cloudwatch:DescribeAnomalyDetectors`
+   - **CloudWatch Logs**: `logs:DescribeLogGroups`, `logs:DescribeLogStreams`, `logs:GetLogEvents`, `logs:FilterLogEvents`, `logs:StartQuery`, `logs:StopQuery`, `logs:GetQueryResults`, `logs:DescribeQueries`
+   - **X-Ray**: `xray:BatchGetTraces`, `xray:GetTraceSummaries`, `xray:GetTraceGraph`, `xray:GetServiceGraph`, `xray:GetTimeSeriesServiceStatistics`
+   - **CloudTrail**: `cloudtrail:LookupEvents`, `cloudtrail:DescribeTrails`, `cloudtrail:GetTrail`, `cloudtrail:ListTrails`, `cloudtrail:GetEventSelectors`
+   - **Application Signals**: `application-signals:GetService`, `application-signals:ListServices`, `application-signals:ListServiceOperations`, `application-signals:GetServiceLevelObjective`, `application-signals:ListServiceLevelObjectives`, `application-signals:BatchGetServiceLevelObjectiveBudgetReport`
    - `synthetics:GetCanary`, `synthetics:GetCanaryRuns` for canary analysis
    - `s3:GetObject`, `s3:ListBucket` for canary artifacts
    - `iam:GetRole`, `iam:ListAttachedRolePolicies`, `iam:GetPolicy`, `iam:GetPolicyVersion` for enablement guides
@@ -134,6 +134,7 @@ stats count() as requestCount,
 by endpoint
 | filter requestCount > 10
 | sort p95Duration desc
+| limit 100
 ```
 
 ### Error Rate Over Time

plugins/aws-observability/skills/aws-observability/references/alerting-setup.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This steering file provides guidance for setting up effective CloudWatch alarms using recommended configurations and best practices.
+This reference provides guidance for setting up effective CloudWatch alarms using recommended configurations and best practices.
 
 ## Core Concepts
 
@@ -171,18 +171,18 @@ Rationale:
 **Recommended Configuration**:
 
 ```
-Metric: AWS/DynamoDB - UserErrors
+Metric: AWS/DynamoDB - ReadThrottleEvents / WriteThrottleEvents
 Statistic: Sum
-Threshold: > 10 errors
+Threshold: > 10 throttle events
 Evaluation Period: 1 minute
 Datapoints to Alarm: 2 out of 2
 Treat Missing Data: notBreaching
 
 Rationale:
-- Sum is correct for error counts
-- 10 errors indicates capacity issue
+- Sum is correct for throttle event counts
+- 10 throttle events indicates a capacity or hot-partition issue
 - 1-minute periods for quick detection
-- 2 out of 2 confirms sustained throttling
+- 2 out of 2 confirms sustained throttling, not a single spike
 ```
 
 ## Composite Alarms

plugins/aws-observability/skills/aws-observability/references/application-signals-setup.md

@@ -1,6 +1,6 @@
 # Application Signals Setup and Enablement Guide
 
-This steering file provides comprehensive guidance for setting up AWS Application Signals using the plugin's enablement guide feature.
+This reference provides comprehensive guidance for setting up AWS Application Signals using the plugin's enablement guide feature.
 
 ## Quick Start: Get Enablement Guide
 

plugins/aws-observability/skills/aws-observability/references/cloudtrail-data-source-selection.md

@@ -2,9 +2,9 @@
 
 ## Purpose
 
-This is a utility guide referenced by `security-auditing.md` and other steering files for CloudTrail data access priority logic. It is not intended to be loaded directly in response to user queries. For CloudTrail security analysis, use `security-auditing.md` instead.
+This is a utility guide referenced by `security-auditing.md` and other reference files for CloudTrail data access priority logic. It is not intended to be loaded directly in response to user queries. For CloudTrail security analysis, use `security-auditing.md` instead.
 
-This steering file defines the priority order for accessing CloudTrail audit data across different AWS services. It ensures the agent always uses the most efficient and comprehensive data source available.
+This reference defines the priority order for accessing CloudTrail audit data across different AWS services. It ensures the agent always uses the most efficient and comprehensive data source available.
 
 ## Data Source Priority
 
@@ -339,7 +339,7 @@ This priority-based approach ensures:
 - Graceful fallback to available alternatives
 - Clear guidance for users on capabilities
 - Cost optimization through appropriate tool selection
-- Consistent behavior across all steering files
+- Consistent behavior across all reference files
 
 ---
 

plugins/aws-observability/skills/aws-observability/references/incident-response.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This steering file provides comprehensive guidance for responding to incidents and troubleshooting issues using the full AWS observability stack.
+This reference provides comprehensive guidance for responding to incidents and troubleshooting issues using the full AWS observability stack.
 
 ## Incident Response Framework
 

plugins/aws-observability/skills/aws-observability/references/log-analysis.md

@@ -1,8 +1,8 @@
-# CloudWatch Logs Insights Analysis Steering
+# CloudWatch Logs Insights Analysis
 
 ## Purpose
 
-This steering file provides guidance for using CloudWatch Logs Insights QL syntax for log analysis, troubleshooting, and data extraction via the CloudWatch MCP server.
+This reference provides guidance for using CloudWatch Logs Insights QL syntax for log analysis, troubleshooting, and data extraction via the CloudWatch MCP server.
 
 ## MCP Server Tools
 

plugins/aws-observability/skills/aws-observability/references/observability-gap-analysis.md

@@ -1,8 +1,8 @@
-# Codebase Observability Gap Analysis Steering
+# Codebase Observability Gap Analysis
 
 ## Purpose
 
-This steering file provides guidance for analyzing codebases across major programming languages to identify observability gaps and provide actionable recommendations for instrumentation, logging, metrics, and tracing.
+This reference provides guidance for analyzing codebases across major programming languages to identify observability gaps and provide actionable recommendations for instrumentation, logging, metrics, and tracing.
 
 ## Analysis Framework
 

plugins/aws-observability/skills/aws-observability/references/performance-monitoring.md

@@ -1,8 +1,8 @@
-# Application Signals Performance Monitoring Steering
+# Application Signals Performance Monitoring
 
 ## Purpose
 
-This steering file provides guidance for using AWS CloudWatch Application Signals to monitor application performance, health, and dependencies.
+This reference provides guidance for using AWS CloudWatch Application Signals to monitor application performance, health, and dependencies.
 
 ## Application Signals Overview
 

plugins/aws-observability/skills/aws-observability/references/security-auditing.md

@@ -1,8 +1,8 @@
-# CloudTrail Security Auditing Steering
+# CloudTrail Security Auditing
 
 ## Purpose
 
-This steering file provides guidance for accessing and analyzing CloudTrail audit data for security auditing, compliance monitoring, and governance analysis.
+This reference provides guidance for accessing and analyzing CloudTrail audit data for security auditing, compliance monitoring, and governance analysis.
 
 ## Prerequisites and Data Source Selection
 
@@ -36,7 +36,7 @@ If neither CloudTrail Lake nor CloudWatch Logs available:
 
 **See `cloudtrail-data-source-selection.md` for detailed decision tree and implementation workflow.**
 
-## When to Load This Steering
+## When to Load This Reference
 
 Load this when the user needs to:
 
@@ -194,7 +194,7 @@ lookup_events(
             'AttributeValue': 'DeleteBucket'
         }
     ],
-    StartTime='2024-01-01T00:00:00Z',
+    StartTime='2024-10-01T00:00:00Z',  # Must be within 90 days
     EndTime='2024-12-31T23:59:59Z',
     MaxResults=50
 )
@@ -207,7 +207,7 @@ lookup_events(
 - Basic filtering capabilities
 - No SQL or complex query support
 
-#### Pattern 2: Security Incident Investigation
+#### Security Incident Investigation
 
 ```
 # 1. Identify suspicious activity (failed access attempts)
@@ -230,7 +230,7 @@ fields eventTime, eventName, userIdentity.userName, requestParameters
 | limit 50
 ```
 
-#### Pattern 3: Compliance Audit
+#### Compliance Audit
 
 ```
 # 1. List all IAM changes
@@ -253,7 +253,7 @@ fields eventTime, eventName, userIdentity.userName, requestParameters, responseE
 | limit 100
 ```
 
-#### Pattern 4: Resource Change Tracking
+#### Resource Change Tracking
 
 ```
 # 1. Find specific resource changes (replace with actual resource ARN)