TSYSDevStack/collab/SupportStack/PromptReview-v1.md

# Prompt Review - TSYSDevStack SupportStack Demo Builder

## Executive Summary
As a senior expert prompt engineer and Docker DevOps/SRE, I've conducted a thorough review of the prompt file at `collab/SupportStack/BuildTheStack`. This document outlines the key areas requiring improvement to ensure the prompt produces a robust, reliable, and autonomous demonstration stack.

## Detailed Findings

### 1. Homepage Integration Clarity
**Issue:** The prompt mentions Docker Compose labels for homepage integration but doesn't specify which labels to use (e.g., for Homarr, Organizr, or other homepage tools).

The homepage software we are using is https://github.com/gethomepage/homepage
It is able to directly access the docker socket and integrate containers according to the documentation. 
I am not sure what labels to use, I'm open to suggestions?
Can you research it and pick a standardized scheme?

**Recommendation:** Specify the exact label format required for automatic service discovery. For example:
```
- homepage integration labels (e.g., for Homarr): `com.homarr.icon`, `com.homarr.group`, `com.homarr.appid`
- common homepage labels: `traefik.enable`, `homepage.group`, `homepage.name`, etc.
```

### 2. Resource Constraint Definitions
**Issue:** The "single user demo capacity" is too vague - should define specific CPU, memory, and storage limits.

**Recommendation:** Define concrete resource limits such as:
- CPU: 0.5-1.0 cores per service
- Memory: 128MB-512MB per service (variable based on service type)
- Disk: Limit ephemeral volumes to 1GB per service

That sounds good. And yes, vary it per service type as needed.

### 3. Testing Methodology Clarity
**Issue:** The TDD process is described but doesn't specify if unit tests should be written before integration tests.

**Recommendation:** Clarify the testing hierarchy:
- Unit tests for individual service configuration
- Integration tests for service-to-service communication
- End-to-end tests for complete workflow validation
- Performance tests for resource constraints

That sounds good.

### 4. Error Handling Strategy
**Issue:** The autonomous error resolution has broad statements but lacks specific failure scenarios and recovery procedures.

**Recommendation:** Define specific scenarios:
- Container startup failures
- Service unavailability
- Resource exhaustion
- Network connectivity issues
- Include specific retry logic with exponential backoff
- Specify maximum retry counts and escalation procedures

That sounds good. I will defer that to you to define all of that using best common practices.

### 5. Security Requirements
**Issue:** Missing security best practices for Docker containers.

**Recommendation:** Include:
- Run containers as non-root users where possible
- Enable read-only filesystems where appropriate
- Implement security scanning during build process
- Define network policies for internal communication only
- Specify how to handle secrets securely (not just environment variables)

All of that sounds good. Secrets via environment variables is fine, as this is only a demo version of the stack. Once its fully working/validated (by you and by me) we will have a dedicated conversation to turn it into a production ready stack.

### 6. Environment Variables Management
**Issue:** Settings file is mentioned but doesn't specify how secrets should be handled differently from regular configuration.

**Recommendation:** Define:
- Separate handling for secrets vs configuration
- Use of Docker secrets for sensitive data
- Environment-specific configuration files
- Validation of required environment variables at startup

Since its a demo, lets keep it simple, everything in the one file please.

### 7. Dependency Management
**Issue:** No mention of how to handle dependencies between components in the right order.

**Recommendation:** Define:
- Explicit service dependencies in Docker Compose
- Service readiness checks before starting dependent services
- Proper startup order using `depends_on` with health checks
- Circular dependency detection and resolution

I agree that is needed. I accept your recommendation. Please define everything accordingly as you work.



### 8. Monitoring and Observability
**Issue:** Health checks are mentioned but need more specificity about metrics collection, logging standards, and alerting criteria.

**Recommendation:** Include:
- Centralized logging to a dedicated service or stdout
- Metrics collection intervals and formats
- Health check endpoint specifications
- Alerting thresholds and notification mechanisms

This is a demo stack. No need for that.

### 9. Version Management
**Issue:** No guidance on container image versioning strategy.

**Recommendation:** Specify:
- Use of pinned image tags rather than 'latest'
- Strategy for updating and patching images
- Rollback procedures for failed updates
- Image vulnerability scanning requirements

I agree with the pinned image tags rather than 'latest'
The rest, lets defer to the production stack implementation.

### 10. Performance Benchmarks
**Issue:** The "single user demo" requirement lacks specific performance metrics.

**Recommendation:** Define:
- Maximum acceptable response times (e.g., <2s for homepage)
- Concurrent connection limits
- Throughput expectations (requests per second)
- Resource utilization thresholds before triggering alerts

I defer to your expertise. This is meant for single user demo use. Use your best judgment.

### 11. Configuration Management
**Issue:** No clear separation between required vs optional configuration parameters.

**Recommendation:** Define:
- Required vs optional environment variables
- Default values for optional parameters
- Configuration validation at runtime
- Configuration change procedures without service restart

The minium viable needed for a demo/proof of concept for now. 
Defer the rest until we work on the production stack please.

### 12. Rollback and Recovery Procedures
**Issue:** Autonomous error resolution is mentioned, but recovery procedures for failed components are not detailed.

**Recommendation:** Specify:
- How to handle partial failures
- Data consistency procedures
- Automated rollback triggers
- Manual override procedures for critical situations

Handle what you can. If you can't handle something after a few tries, flag it in collab/SupportStack/HUMANHELP.md and move on.
Also keep a running status report in collab/SupportStack/STATUS.md 
Use git commit heavily.
Push whenever you have a component fully working/tested/validated.

### 13. Cleanup and Teardown
**Issue:** The control script includes uninstall but doesn't specify what "uninstall" means in terms of cleaning up volumes, networks, and other Docker resources.

**Recommendation:** Define:
- Complete removal of all containers, volumes, and networks
- Cleanup of temporary files and logs
- Verification of complete cleanup
- Handling of orphaned resources

Yes all of that is needed. 

### 14. Documentation Requirements
**Issue:** The prompt mentions documentation files but doesn't specify what documentation should be created for each component.

**Recommendation:** Include requirements for:
- Component architecture diagrams
- Service configuration guides
- Troubleshooting guides
- Startup/shutdown procedures
- Monitoring and health check explanations

Defer that to production. For now, we just want the MVP and then the full stack POC/demo.

## Priority Actions
1. **High Priority:** Resource constraints, security requirements, and homepage integration specifications
2. **Medium Priority:** Error handling, testing methodology, and dependency management
3. **Lower Priority:** Documentation requirements and version management (though important for production)

## Conclusion
The prompt has a solid foundation but needs these clarifications to ensure the implementation will be truly autonomous, secure, and reliable for the intended use case. Addressing these issues will result in a much more robust and maintainable solution.

For everything that I've said to defer, please track those items in collab/SupportStack/ProdRoadmap.md (make it beautiful with table of contents, headers, tables, icons etc).

I defer to your prompt engineering expertise to update the prompt as needed to capture all of my answers.